PDFUserGuide.xml
<?xml version="1.0"?>
<!DOCTYPE pdf PUBLIC "-//big.faceless.org//report" "report-1.1.dtd">
<!--
$Id: PDFUserGuide.xml.txt,v 1.1.1.1 2007-06-05 15:52:38 mike Exp $
This document contains the user manual for the Big Faceless PDF Library,
and demonstrates many of the features of the Report Generator.
-->
<pdf lang="en_US">
<head>
<script>
function showform()
{
var s="";
s += "You entered '"+this.getField("sampletext").value+"' in the text box\n";
s += "You selected '"+this.getField("samplechoice").value+"' from the menu\n";
s += "The checkboxes are "+this.getField("samplecheck1").value+", "+this.getField("samplecheck2").value+" and "+this.getField("samplecheck3").value+"\n";
s += "You selected the "+this.getField("sampleradio").value+" radio button\n";
app.alert(s);
}
</script>
<meta name="layout" value="one-column"/>
<meta name="author" value="Big Faceless Organization."/>
<meta name="show-bookmarks" value="true"/>
<style>
body { font-size:11; }
h1 { font-size:18pt; font-weight:bold; font-family:Helvetica; margin-bottom:10; margin-top:20; }
h2 { font-size:14pt; font-style:italic; font-family:Helvetica; margin-top:10; }
/**
* This controls the look of any blocks with class="example". We set the
* margins to indent it slightly, set the font, and force the example to be
* 100% of the width
*/
.example { margin-left:10; margin-right:10; margin-top:1em;
padding:11; border:thin solid black; width:100%;
background-color:#D0ECEC; font:9pt Courier;
page-break-before:avoid;
}
.sexample { margin-left:10; margin-right:10; margin-top:1em;
padding:11; border:thin solid black; width:100%;
background-color:#D0ECEC; font:8pt Courier;
page-break-before:avoid;
}
div.example > p:first-child { margin-top:0 }
div.example > p:last-child { margin-bottom:0 }
div.note > p:first-child { margin-top:0 }
div.note > h1:first-child { margin-top:0 }
div.note > h2:first-child { margin-top:0 }
div.note > h3:first-child { margin-top:0 }
div.note > h4:first-child { margin-top:0 }
div.note > p:last-child { margin-bottom:0 }
div.note[float=right] { margin-left:10; }
div.note[float=left] { margin-right:10; }
/**
* This controls the look of any blocks with class="note". We set the
* background to be a star pattern in light red, set the left and right
* margins to indent the block slightly and set the corner radius to be 10
* points.
*/
.note { margin-left:10; margin-right:10;
padding:10; corner-radius:10; border:thin solid black;
background-color:pattern(star,#FFE0E0,#FFD4D4,50);
font-size:10; font-family:Helvetica; font-style:italic;
}
/**
* If we use an h2 inside a paragraph of class="note", clear the top margin
*/
.note h2 { margin-top:0; }
/**
* This class is used to style certain tables that contain definitons
*/
.defns { margin-left:10; margin-right:10; margin-top:0;
padding:4; border:thin solid black; width:100%; cellpadding:4;
background-color:#E4F4F4; font-size:9; font-family:Helvetica;
}
.defns th { border-bottom:thin solid black; font-style:italic; }
.defns td:first-child { font-family:Courier; padding-right:0.2in; white-space:nowrap }
.caption { align:center; font:9pt italic Times; margin-top:2; margin-bottom:15; page-break-before:avoid; }
/**
* Set the background color for the table with id="tableColorPatterns"
*/
#tableColorPatterns { background-color:#E4F4F4; }
.imgexample { border:thin solid black; background-color:#E4F4F4 }
.imgexamplehead { border:thin solid black; width:100%; align:center; padding:4; background-color:#D0ECEC; }
.patternxmp { width:30%; height:40; border:thin solid black; }
.patterndsc { width:70%; height:40; padding:5; border:thin solid black; }
#page1 { background-macro:page1watermark }
</style>
<bookmarklist>
<bookmark name="Introduction" href="#Introduction"/>
<bookmark name="Installation" href="#Introduction"/>
<bookmark font-weight="bold" name="Creating New PDFs" href="#CreatingNewPDF"/>
<bookmark name="Defining Styles" href="#Styles"/>
<bookmark name="Colors" href="#Colors">
<bookmark name="Calibrated and Spot Colors" href="#ICCColors"/>
<bookmark name="Transparency" href="#Transparency"/>
<bookmark name="Patterns" href="#Patterns"/>
</bookmark>
<bookmark name="Using Text" href="#Text"/>
<bookmark name="Formatting Text" href="#FormattingText" expanded="true">
<bookmark name="Using the drawText method" href="#textDrawText"/>
<bookmark name="Using the LayoutBox class" href="#textLayoutBox" expanded="true">
<bookmark name="Combining text and images" href="#textLayoutBoxImages"/>
<bookmark name="Finding the position of a phrase" href="#textLayoutBoxText"/>
<bookmark name="Vertical positioning" href="#textLayoutBoxVertical"/>
<bookmark name="Floating boxes" href="#textLayoutBoxFloating"/>
</bookmark>
</bookmark>
<bookmark name="Advanced Text" href="#AdvancedText">
<bookmark name="Quotes" href="#Quotes"/>
<bookmark name="Kerning" href="#Kerning"/>
<bookmark name="Text Measurement" href="#TextMeasurement"/>
</bookmark>
<bookmark name="International support" href="#International"/>
<bookmark name="Character Availability" href="#CharacterAvailable"/>
<bookmark name="Unicode" href="#Unicode"/>
<bookmark name="Bitmap Graphics" href="#BitmapGraphics"/>
<bookmark name="Vector Graphics" href="#LineGraphics"/>
<bookmark name="Graphics State" href="#Transforms"/>
<bookmark name="Graphics Style" href="#GraphicsStyle"/>
<bookmark font-weight="bold" name="Editing existing PDF documents" href="#Manipulating"/>
<bookmark name="Hyperlinks and Annotations" href="#Interaction">
<bookmark name="Actions" href="#Actions"/>
<bookmark name="Hyperlinks" href="#Hyperlinks"/>
<bookmark name="Other Annotations" href="#OtherAnnotations"/>
</bookmark>
<bookmark name="Interactive Forms" href="#Forms">
<bookmark name="Interactive Forms" href="#Events"/>
</bookmark>
<bookmark name="Digital Signatures" href="#Signatures">
<bookmark name="Adobe Self-Sign signatures" href="#SelfSignSignatures"/>
<bookmark name="VeriSign™ signatures" href="#VeriSignSignatures"/>
<bookmark name="Verifying existing signatures" href="#SignatureVerifying"/>
<bookmark name="Additional notes on signatures" href="#SignatureProvisos"/>
</bookmark>
<bookmark name="Special Features">
<bookmark name="Sounds" href="#Sound"/>
<bookmark name="Bookmarks" href="#Bookmarks"/>
<bookmark name="Encryption and Access Levels" href="#Encryption"/>
<bookmark name="Bar Codes" href="#BarCodes"/>
<bookmark name="Meta Information and Layout" href="#LayoutMeta"/>
<bookmark name="XML Metadata (Adobe XMP™)" href="#XML"/>
<bookmark name="Preflighting / Output profiles" href="#OutputProfiles"/>
</bookmark>
<bookmark name="PDF Viewer Extension" expanded="true">
<bookmark name="About the Extension" href="#ParserIntro"/>
<bookmark name="Converting PDFs to TIFF" href="#ParserTIFF"/>
<bookmark name="Printing PDFs" href="#ParserPrint"/>
<bookmark name="Extracting text" href="#ParserTextExtraction"/>
<bookmark name="Extracting images" href="#ParserImageExtraction"/>
</bookmark>
<bookmark name="Appendix A: Warning Messages" href="#AppendixA"/>
<bookmark name="List of Examples">
<bookmark name="1. Hello World" href="#exampleHelloWorld?zoom=fit"/>
<bookmark name="2. Colors" href="#exampleColors?zoom=fit"/>
<bookmark name="3. Custom Patterns" href="#exampleCustomPattern?zoom=fit"/>
<bookmark name="4. OpenType fonts" href="#exampleOpenType?zoom=fit"/>
<bookmark name="5. Formatting Text" href="#exampleFormatText?zoom=fit"/>
<bookmark name="6. LayoutBox Text" href="#exampleTextLayoutBox?zoom=fit"/>
<bookmark name="7. Mixing Text and Images" href="#exampleTextInlineImage?zoom=fit"/>
<bookmark name="8. Text on Colored backgrounds" href="#exampleTextTwin?zoom=fit"/>
<bookmark name="9. Floating Text" href="#exampleTextFloat?zoom=fit"/>
<bookmark name="10. Bitmap Images" href="#exampleShowImage?zoom=fit"/>
<bookmark name="11. Drawing Circles" href="#exampleDrawCircle?zoom=fit"/>
<bookmark name="12. Path Operations" href="#exampleDrawPath?zoom=fit"/>
<bookmark name="13. Save and Undo" href="#exampleSaveUndo?zoom=fit"/>
<bookmark name="14. Editing existing documents" href="#exampleConcatenate?zoom=fit"/>
<bookmark name="15. Cloning an existing document" href="#exampleClone?zoom=fit"/>
<bookmark name="16. Stamping a document" href="#exampleStamp?zoom=fit"/>
<bookmark name="17. Stamping under a document" href="#exampleUnderStamp?zoom=fit"/>
<bookmark name="18. Page Templates" href="#exampleTemplate?zoom=fit"/>
<bookmark name="19. Concatenating Forms" href="#exampleConcatenateForm?zoom=fit"/>
<bookmark name="20. LayoutBox Hyperlinks" href="#exampleLayoutBoxLink?zoom=fit"/>
<bookmark name="21. Text Hyperlinks" href="#exampleTextLink?zoom=fit"/>
<bookmark name="22. Reading and Writing Forms" href="#exampleFormSimple?zoom=fit"/>
<bookmark name="23. Creating Forms" href="#exampleFormCreation?zoom=fit"/>
<bookmark name="24. Applying Signatures" href="#exampleSig1?zoom=fit"/>
<bookmark name="25. Verifying Signatures" href="#exampleSig2?zoom=fit"/>
<bookmark name="26. Access Control and Passwords" href="#example40BitEncryption?zoom=fit"/>
<bookmark name="27. Defining Custom Canvases" href="#exampleCustomCanvas?zoom=fit"/>
<bookmark name="28. Using Output Profiles" href="#exampleOutputProfile?zoom=fit"/>
<bookmark name="29. Converting a PDF to TIFF" href="#exampleParserTIFF?zoom=fit"/>
<bookmark name="30. Printing a PDF" href="#exampleParserPrint?zoom=fit"/>
<bookmark name="31. Extracting text from a PDF" href="#exampleParserTextExtraction?zoom=fit"/>
<bookmark name="32. Extracting images from a PDF" href="#exampleParserImageExtraction?zoom=fit"/>
</bookmark>
<bookmark name="List of Tables">
<bookmark name="Common PDFStyle methods" href="#tablePDFStyle"/>
<bookmark name="Color Patterns" href="#tableColorPatterns"/>
<bookmark name="Unicode Control Characters" href="#tableUnicodeControlChars"/>
<bookmark name="Summary of Actions" href="#tableActions"/>
</bookmark>
<bookmark name="List of Notes">
<bookmark name="Page Coordinates" href="#notePageCoordinates?zoom=fit"/>
<bookmark name="Outline or Solid?" href="#noteOutlineSolid?zoom=fit"/>
<bookmark name="Standard Fonts" href="#noteStandardFonts?zoom=fit"/>
<bookmark name="Kerning & Ligatures" href="#noteKerning?zoom=fit"/>
<bookmark name="Interactive Forms" href="#noteFormElements?zoom=fit"/>
</bookmark>
</bookmarklist>
<macrolist>
<macro id="page1watermark">
<img width="612" height="131" position="absolute" src="resources/pdflibrary.jpg"/>
</macro>
<macro id="footer">
<p font-size="9" font="Times" width="100%" border-top="thin solid black" padding-top="5" margin-top="5" align="center">
Page <pagenumber/> of <totalpages/>
</p>
</macro>
</macrolist>
</head>
<body size="Letter" footer="footer" footer-height="25">
<h1 padding-top="130" font-size="36" width="100%" height="50%" align="center">
The Big Faceless PDF Library
<br/>
<br/>
<small>version 2.6.2</small>
<br/>
<br/>
User Guide
</h1>
<pbr />
<h1 id="Introduction">Introduction</h1>
<p>
Thank you for your interest in the <a href="http://big.faceless.org/products/pdf">Big
Faceless PDF Library</a>. This userguide will give you an overview of what the library
is capable of, and start you off with some simple examples. For more detailed information,
please see the API documentation supplied in HTML format with this package, and look at
the examples supplied with the package.
</p>
<h2>What is it?</h2>
<p>
The Big Faceless PDF Library is a collection of classes which allow easy
creation of PDF® documents from Java™. When linked with your own application, it
can be used to rapidly create PDFs (like this userguide) from applications,
Applets or Servlets.
</p>
<p>
The library is small, fast, easy to use and integrate into your projects, and is
written in 100% pure Java (requires Java 1.2 or later). It's well documented and
comes with many examples, and as it uses no native code or third-party packages
it's easy install and run from applications, EJB's or Servlets on any Java 1.2 platform.
</p>
<h2>Features</h2>
<p>
Here's a brief summary of the libraries features, for the impatient.
</p>
<ul>
<li>
Extract text and images from PDFs, display them or convert them to TIFF with the <b>Viewer
Extension</b>
</li>
<li>
Native Unicode™ support, even in the document body. No worrying about
codepages and encodings, it <i>just works</i>.
</li>
<li>Full support for creating and editing AcroForms</li>
<li>Edit existing PDF documents with the <code>PDFReader</code> class.</li>
<li>40 and 128-bit encryption using RC4 or AES, for eyes-only documents.</li>
<li>Digitally sign documents for authenticity and non-repudiation</li>
<li>Extend the library with custom Signature and Encryption handlers</li>
<li>Full embedding of TrueType or Type 1 fonts, with subsetting for smaller fonts.</li>
<li>Japanese, Chinese and Korean font support</li>
<li>Right to left and bi-directional text is fully supported.</li>
<li>Embed JPEG, PNG, GIF, PNM, TIFF or <tt>java.awt.Image</tt> images.</li>
<li>Supports Adobes XMP™ specification, for embedding and extracting XML metadata
from PDF documents</li>
<li>Add hyperlinks to text or images</li>
<li>Add Annotations and Audio samples to the document</li>
<li>Insert many different types of barcode directly - no Barcode font required!</li>
<li>Better text layout with track and pair kerning, ligatures and justification</li>
<li>Paint text or graphics using "patterns"</li>
<li>Simplify complex documents by defining and applying <i>"Styles"</i>.</li>
<li>Full support for PDF features like bookmarks, compression and document meta-information</li>
<li>Non-linear creation of documents - pages can be created and edited in any order.</li>
<li>Intelligent embedding. Fonts and images can be reused without increasing the file size.</li>
</ul>
<p>
The library <i>officially</i> only produces PDFs that are valid on <b>Acrobat 4.0 and
up</b> (although most documents will work under Acrobat 3.0 as well, we don't support it).
The library output has been verified against Acrobat 4.0, 5.0 and 6.0 on Windows, along with
numerous PDF viewers on other platforms (including Linux and OS/X).
</p>
<h1 id="Installation">Installation</h1>
<p>
Installing the library is as simple as unpacking it and adding the file
<tt>bfopdf.jar</tt> to your <tt>CLASSPATH</tt>. You'll find several other files in the
package, including <tt>README.txt</tt>, containing the overview of the package,
<tt>docs/LICENSE.txt</tt> containing the licencing agreement, and the <tt>docs</tt> and
<tt>example</tt> directories containing the API documentation and the examples
respectively.
</p>
<h1 id="CreatingNewPDF">Section 1. Creating new PDF documents</h1>
<h2>The Classic Example</h2>
<pre id="exampleHelloWorld" class="example">
1. import java.io.*;
2. import java.awt.Color;
3. <b>import org.faceless.pdf2.*;</b>
4.
5. public class HelloWorld
6. {
7. public static void main(String[] args) throws IOException
8. {
9. <b>PDF pdf = new PDF();</b>
10.
11. <b>PDFPage page = pdf.newPage(PDF.PAGESIZE_A4);</b>
12.
13. <b>PDFStyle mystyle = new PDFStyle();</b>
14. <b>mystyle.setFont(new StandardFont(StandardFont.HELVETICA), 24);</b>
15. <b>mystyle.setFillColor(Color.black);</b>
16.
17. <b>page.setStyle(mystyle);</b>
18. <b>page.drawText("Hello, World!", 100, page.getHeight()-50);</b>
19.
20. OutputStream out = new FileOutputStream("HelloWorld.pdf");
21. <b>pdf.render(out);</b>
22. out.close();
23. }
24. } </pre><p class="caption">Example 1 - A "Hello World" program</p>
<p>
It doesn't get simpler than the classic <tt>HelloWorld</tt> example - a copy of which is
included in the <tt>example</tt> sub-directory of the package, so you can try it yourself.
<br/>
<br/>
A quick glance at this example reveals several points to remember when using the library.
</p>
<ul margin-bottom="1em">
<li>
The package is called <tt>org.faceless.pdf2</tt>, and the main class is the <tt>PDF</tt>
class.
</li>
<li>
Each PDF document is made of <i>pages</i>, which contain the visible contents of the
PDF.
</li>
<li>Fonts and colors are set using a <i>style</i>, which is then applied to the page.</li>
<li>
The completed document is sent to an <tt>OutputStream</tt>, which can be a file, a
servlet response, a <tt>ByteArrayOutputStream</tt> or anything else.
</li>
</ul>
<p>
<div width="55%" class="note" float="right" id="notePageCoordinates">
<h1><zapf>➽</zapf> Page Co-ordinates</h1>
<p>
By default, pages are measured from their bottom-left corner in <b>points</b>
(1/72nd of an inch). So <code>(100, page.getHeight()-50)</code> is 100 points in from
the left and 50 points down from the top of the page.
</p>
<p>
You can change this using the <tt>setUnits</tt> method of the
<tt>PDFPage</tt> class, to measure in inches, centimeters etc. from
any corner of the page. See the API documentation for more info.
</p>
</div>
In this example, we've used one of the "standard" 14 fonts that are guaranteed to
exist in all PDF viewers, <span font="Helvetica">Helvetica</span>. If this isn't
enough, the library can embed TrueType™ and Adobe Type 1 fonts, or for Chinese,
Japanese and Korean other options exist. We'll cover more on fonts later.
<br/>
<br/>
Colors are defined with the standard <tt>java.awt.Color</tt> class. A PDF document can
has two different colors - a <i>line color</i> for drawing the outlines of shapes, and
a <i>fill color</i> for filling shapes. Read on for more on colors.
</p>
<h1 id="Styles">Defining and applying Styles</h1>
<p>
Document creators have found that defining the look of their document with a <i>style</i>,
rather than setting the font, color and so on separately, makes life simpler. Everything
relating to how the content of the page looks is controlled using the <tt>PDFStyle</tt>
class.
</p>
<p>
Some methods in this class relate just to images, and others just to text. Here are some of
the more common ones to get you started.
</p>
<table width="100%" id="tablePDFStyle" class="defns">
<tr>
<td><tt>setFillColor</tt></td>
<td><i><nobr>Text, Graphics</nobr></i></td>
<td>
Sets the color of the interior of the shape. For example, this table has a Fill color
of light gray, while this text has a Fill color of black.
</td>
</tr>
<tr>
<td><tt>setLineColor</tt></td>
<td><i>Text, Graphics</i></td>
<td>
Sets the color of the outline of the shape. This table has a Line color of black.
Setting a Line color on text has no effect, unless the <tt>setFontStyle</tt> method is
used to turn on text outlines.
</td>
</tr>
<tr>
<td><tt>setFont</tt></td>
<td><i>Text</i></td>
<td>
Sets the font and the font size
</td>
</tr>
<tr>
<td><tt>setTextAlign</tt></td>
<td><i>Text</i></td>
<td>
Sets the alignment of the text - left, centered, right or justified, and optionally
the vertical alignment too.
</td>
</tr>
<tr>
<td><tt>setTextUnderline</tt></td>
<td><i>Text</i></td>
<td>
Whether to <u>underline</u> the text. See also
<tt><strike>setTextStrikeout</strike></tt>
</td>
</tr>
<tr>
<td><tt>setTextLineSpacing</tt></td>
<td><i>Text</i></td>
<td>
Determines how far apart each line of text is - single, double spaced, line-and-a-half
or any other value.
</td>
</tr>
<tr>
<td><tt>setTextIndent</tt></td>
<td><i>Text</i></td>
<td>
Sets how far to indent the first line of text, in points.
</td>
</tr>
<tr>
<td><tt>setLineWeighting</tt></td>
<td><i>Graphics, Text</i></td>
<td>
Set the thickness of any lines drawn using the Line color, in points (including outlined
text).
</td>
</tr>
<tr>
<td><tt>setLineDash</tt></td>
<td><i>Graphics</i></td>
<td>
Set the <i>pattern</i> to draw lines with. Normally lines are solid, but you can draw
dashed lines using this method.
</td>
</tr>
<tr>
<td><tt>setLineJoin/<br/>setLineCap</tt></td>
<td><i>Graphics</i></td>
<td>
Determines how the ends of a line are drawn - squared off, rounded and so on. The line
cap is the shape at the end of a line, and the line join is the shape where two lines
meet at a corner.
</td>
</tr>
</table>
<p class="caption">Table 1 - Common methods in the PDFStyle class</p>
<p>
Styles are more than just a useful way of grouping aspects of appearance together - they
help you to <i>manage</i> the look and feel of your document:
</p>
<ul>
<li>
If many different items are meant to have the same look, give them all the same style.
You only need to alter the style once to change their appearance.
</li>
<li>
Styles can be <i>extended</i> - create a copy of a current style and change a single
aspect, and everything else will be inherited.
</li>
<li>
By using a relatively limited number of styles, a document has a more consistent
"look-and-feel".
</li>
<li>
Name your styles <tt>header</tt>, <tt>sourcecode</tt> and so on to get a clearer
perspective of the <i>structure</i> of the document.
</li>
</ul>
<h1 page-break-after="avoid" id="Colors">Colors</h1>
<p>
<div width="50%" class="note" float="right" id="noteOutlineSolid">
<h1><zapf>➽</zapf><o>Outline</o> or Solid?</h1>
<ul>
<li>For outlined shapes, set the Line color only</li>
<li>For solid shapes, set the Fill color only</li>
<li>For both, set both colors!</li>
<li>For text, call <tt>style.setFontStyle()</tt></li>
</ul>
</div>
As you can see from the table to the right, PDF documents have two active colors. The Line
color (or "Stroke" color) is the color used to draw outlines of shapes or text, and
the Fill color is the color used to fill those shapes. Text is normally drawn with
just the fill color, although as you can see opposite you can call the
<tt>style.setFontStyle()</tt> method in the <tt>PDFStyle</tt> class to set text to
outlined, filled and outlined or even invisible (which we've seen used in an OCR
application, so it's not <i>completely</i> useless).
</p>
<h2 id="ICCColors">Calibrated Colors</h2>
<p>
The library has full support for calibrated, or device-independent colors. The PDF
specification allows colors to be calibrated against a <i>ColorSpace</i>, which is
essentially a complex mathematical function which determines exactly which shade of red,
white or black you get. For programmers who are used to working with computer monitors
with a "brightness" and "contrast" knob, the concept of calibrated color may seem a
little alien, but in the print world it's essential.
</p>
<p>
The Java language designers got it correct right from the start, and defined the
excellent <tt>java.awt.Color</tt> class in such a way as to make defining colors simple.
The default color space is a standard known as <tt>sRGB</tt>, which is a W3C standard
and supported by a large number of computer companies. When you specify
<tt>Color.red</tt> in your program, you're actually getting the color "red=100%" in the
sRGB colorspace. Since 1.1.5, all PDF documents generated by the Big Faceless PDF
Library are calibrated to use the sRGB ColorSpace as well.
</p>
<p>
So how do you use other colorspaces? Here's an example:
</p>
<pre id="exampleColors" class="example">
1. <b>import java.awt.color.*;</b>
2. <b>import java.awt.Color;</b>
3.
4. public void colorDemo(PDFPage page)
5. throws IOException
6. {
7. <b>Color red1 = Color.red;</b> <i>// sRGB colorspace, red=100%</i>
8.
9. <i>// Create the same red in an ICC colorspace loaded</i>
10. <i>// from a file. Here we use the NTSC color profile.</i>
11. ICC_Profile prof = ICC_Profile.getInstance("NTSC-Profile.icc");
12. ICC_ColorSpace ntsc = new ICC_ColorSpace(prof);
13. float[] comp = { 1.0f, 0.0f, 0.0f };
14. <b>Color red2 = new Color(ntsc, comp, 1);</b>
15.
16. <i>// Create a yellow color in the device-dependent CMYK</i>
17. <i>// colorspace, supplied with the library.</i>
18. <b>Color yellow = CMYKColorSpace.getInstance().getColor(0,0,1,0);</b>
19.
20. <i>// Create a spot color from the PANTONE™ range</i>
21. SpotColorSpace spot = new SpotColorSpace("PANTONE Yellow CVC", yellow);
22. <b>Color spotyellow = spot.getColor();</b>
23. } </pre><p class="caption">Example 2 - Specifying different colorspaces</p>
<p>
This may seem a complicated example, but first it demonstrates using four different
colorspaces in 20 lines. If it doesn't make sense, then you're probably not going to
need that bit anyway!
</p>
<p>
You may notice we've shown you how to create the colors, but haven't shown you how to
apply the colors to the PDF document. That's because colors created using these
different colorspaces are treated no differently than colors using the normal sRGB
colorspace. Just use the <tt>setFillColor</tt> and <tt>setLineColor</tt> methods like
you would do normally - the colorspace handling is all done behind the scenes.
</p>
<p>
For more information on Spot and CMYK colors, have a look at the Java API documentation
for the <tt>CMYKColorSpace</tt> and <tt>SpotColorSpace</tt> classes that are part of the
PDF library.
</p>
<p>
Some image formats can also use calibrated colors. PNG, TIFF and JPEG images may have an
ICC color profile embedded, which the library will pick up and use automatically (GIF images
do not, but can easily be converted to PNG if necessary). For all of these image formats
and for <tt>java.awt.Image</tt> images as well, if a specific color profile is included as part
of that image format, it will be used automatically.
</p>
<h2 id="Transparency">Transparency and Translucency</h2>
<p page-break-after="avoid">
<div width="250" class="note" float="right" id="noteOutlineSolid">
<h1><zapf>➽</zapf>Translucency</h1>
<p>
<div width="100" height="100" float="left">
<circle position="absolute" left="50%" top="30%" border="0" background-color="alpha(50%,red)" radius="25%"/>
<circle position="absolute" left="32.7%" top="60%" border="0" background-color="alpha(50%,green)" radius="25%"/>
<circle position="absolute" left="67.3%" top="60%" border="0" background-color="alpha(50%,blue)" radius="25%"/>
</div>
Those viewing this document in Acrobat 5.0 or greater should
see a typical color-blend here. Earlier viewers will probably
display three opaque circles, with blue on top
</p>
</div>
The release of Acrobat 5.0 introduced the concept of <i>translucent</i> colors to PDF,
and since version 2.0 this is supported with the PDF library as well. The measure of
transparency in a color is known as it's <i>alpha value</i> - a color with an alpha
of 0.0 is completely transparent, while an alpha value of 1.0 is completely opaque.
Specifying a color with an alpha value in Java is easily done - there are a number
of constructors in the <code>java.awt.Color</code> class that take an alpha value.
<br/><br/>
For example, the image to the right shows three translucent circles. These are simply
drawn by setting the fill color to <tt>new Color(1, 0, 0, 0.5f)</tt>,
<tt>new Color(0, 1, 0, 0.5f)</tt> and <tt>new Color(0, 0, 1, 0.5f)</tt>
respectively, applying the style and drawing the circles on the page.
<br/><br/>
Translucency is also supported in the PNG and GIF image formats - basically, if you
load an image with translucent colors, then assuming the PDF viewer is Acrobat 5 or
later, then the image will be displayed correctly.
</p>
<h2 id="Patterns">Patterns</h2>
<p page-break-after="avoid">
As well as solid colors, patterns and gradients can be used for special effects (for instance,
the box on the top right of this page has a background pattern of stars). Several pre-defined
patterns exist, or more advanced users can define their own. The <code>PDFPattern</code>
class implements the <code>java.awt.Paint</code> interface, and so can be be passed into
the <code>setLineColor</code> and <code>setFillColor</code> methods of a <code>PDFStyle</code>.
to fill
<span font-style="filled outline" outline-color="black" outline-width="0.4" color="pattern(stripe,#FF0000,#0000FF,2,2)">text or shapes with a pattern.</span>
</p>
<table page-break-inside="auto" id="tableColorPatterns" width="100%" border="1">
<tr>
<td width="40%" class="patternxmp" background-color="pattern(stripe,#A0A0FF,#0000FF,5,5,30)"></td>
<td class="patterndsc">
The <tt>"StripeXX"</tt> pattern creates a pattern of alternating stripes. "XX" may be
any number of 0 to 360, and specifies the angle of the stripes in degrees. The box to
the left, for example, was created using <tt>new PDFPattern("Stripe30", 0, 0, 10, 10, color1, color2)</tt>.
</td>
</tr>
<tr>
<td class="patternxmp" background-color="pattern(stripe,#FFA0A0,#FF0000,15,5,0)"></td>
<td class="patterndsc">
Here is another example of a <tt>"Stripe"</tt>, with vertical stripes and a
different width for each stripe color. This is equivalent to <tt>("Stripe0", 0, 0, 15, 5, color1, color2)</tt>
</td>
</tr>
<tr>
<td class="patternxmp" background-color="pattern(brick,#A0A0FF,#0000FF,30,15)"></td>
<td class="patterndsc">
This is the pattern called <tt>"Brick"</tt>. For budding brickies, this style of brick
laying is known as a running pattern bond.
</td>
</tr>
<tr>
<td class="patternxmp" background-color="pattern(check,#FFA0A0,#FF0000,10)"></td>
<td class="patterndsc">
This check pattern is created by passing <tt>"Check"</tt> to the PDFPattern constructor.
</td>
</tr>
<tr>
<td class="patternxmp" background-color="pattern(grid,#A0A0FF,#0000FF,2,18)"></td>
<td class="patterndsc">
This pattern is created by calling <tt>new PDFPattern("Grid", 0, 0, 20, 20, color1, color2)</tt>
</td>
</tr>
<tr>
<td class="patternxmp" background-color="pattern(spot,#FFA0A0,#FF0000,10)"></td>
<td class="patterndsc">
A spot pattern similar to the pattern used for half-toning in newspapers can be
created by passing in "Spot" to the constructor.
</td>
</tr>
<tr>
<td class="patternxmp" background-color="pattern(polka,#A0A0FF,#0000FF,20)"></td>
<td class="patterndsc">
This pattern is created by calling <tt>new PDFPattern("Polka", 0, 0, 20, 20, color1, color2)</tt>
</td>
</tr>
<tr>
<td class="patternxmp" background-color="pattern(star,#FFA0A0,#FF0000,20)"></td>
<td class="patterndsc">
Finally, a pattern of repeating 5-pointed stars (like those on the US flag) can be
created with the "Star" pattern.
be set
</td>
</tr>
</table>
<p class="caption">Table 2 - Color patterns</p>
<h3 id="CustomPatterns">Custom Patterns</h3>
<p>
Custom patterns can be created in one of two ways. First, a <code>PDFCanvas</code> can
be created and a pattern drawn onto it. This can then be used as a tile to paint with.
Here's a simple example showing how to paper the page with yellow smiley faces.
</p>
<pre class="example" id="exampleCustomPattern">
1. PDFCanvas tile = new PDFCanvas(40, 40);
2. PDFStyle style = new PDFStyle();
3. style.setFillColor(Color.yellow);
4. style.setLineColor(Color.black);
5. tile.setStyle(style);
6. tile.drawCircle(20, 20, 15); <i>// Draw the face</i>
7. tile.drawCircleArc(20, 20, 11, 110, 250); <i>// Add a smile...</i>
8. tile.drawCircle(15, 25, 2); <i>// ...and two eyes</i>
9. tile.drawCircle(25, 25, 2);
10. tile.flush(); <i>// Optional but a good idea</i>
11.
12. <b>PDFPattern pattern = new PDFPattern(tile, 0, 0, 40, 40);</b>
13.
14. PDFStyle pagestyle = new PDFStyle(); <i>// Now fill the page</i>
15. <b>pagestyle.setFillColor(pattern);</b>
16. page.setStyle(pagestyle);
17. page.drawRectangle(0, 0, page.getWidth(), page.getHeight()); </pre>
<p class="caption">Example 3 - Creating your own patterns</p>
<p>
A second method, for those that know something about the internals of PDF, is
to define a pattern as a sequence of PDF operators in a resource file. We'll
cover this in more detail in a <a href="#CreatingCustomCanvases">later section</a>.
</p>
<h1 id="Text">Text and Fonts</h1>
<p>
<div width="30%" class="note" float="right" whitespace="nowrap" margin-bottom="5" id="noteStandardFonts">
<h2>Standard 14 fonts</h2>
<p font-style="normal" font-weight="normal" margin-bottom="0">
<span font="Times">Times</span><br/>
<span font="Times"><i>Times-Italic</i></span><br/>
<span font="Times"><b>Times-Bold</b></span><br/>
<span font="Times"><b><i>Times-BoldItalic</i></b></span><br/>
<span font="Helvetica">Helvetica</span><br/>
<span font="Helvetica"><i>Helvetica-Oblique</i></span><br/>
<span font="Helvetica"><b>Helvetica-Bold</b></span><br/>
<span font="Helvetica"><b><i>Helvetica-BoldOblique</i></b></span><br/>
<span font="Courier">Courier</span><br/>
<span font="Courier"><i>Courier-Oblique</i></span><br/>
<span font="Courier"><b>Courier-Bold</b></span><br/>
<span font="Courier"><b><i>Courier-BoldOblique</i></b></span><br/>
<symbol>ΑαΒβΓγ</symbol> (Symbol)<br/>
<zapf>♠♣♥♦</zapf> (ZapfDingbats)<br/>
</p>
</div>
Document developers have a large choice when it comes to choosing a font for their
document. First, every PDF document is guaranteed to have a set of 14 base fonts
available to it, which the library calls "Standard" fonts. These are available via
the <tt>StandardFont</tt> class, an example of which you've already seen in the
"HelloWorld" example.
<br/><br/>
Secondly for Chinese, Japanese and Korean, Adobe has defined a set of standard fonts
which are available in every PDF viewer, <i>providing the correct language pack is
installed</i>. The language packs are part of the appropriate regional versions of
Adobe Acrobat, or can be downloaded as separate packs for other versions of Acrobat.
Other PDF viewers will have different requirements.
These fonts are available via the <tt>StandardCJKFont</tt> package.
<br/><br/>
Finally, a document can contain both Adobe "Type 1" and OpenType™ fonts. Many users
will have heard instead of <i>TrueType</i>™ fonts, which is a format developed
jointly by Apple and Microsoft (many TrueType fonts are marked as "Apple" or "Windows"
specific - the library works with either). A few years back Microsoft and Adobe finally
made peace, and the two companies combined their competing formats into the
"OpenType" format - so TrueType is a subset of OpenType. As of 2.3 we also support
OpenType fonts with PostScript glyphs (which typically have a suffix of ".otf" rather
than ".ttf)
<br/><br/>
Both Type 1 and OpenType fonts can be either be <i>embedded</i> or <i>referenced</i>
in the document. Referencing the font requires the font to be available already on the
target platform - because of this it's not really suitable unless your document is
going to a limited audience, all of whom you know have the font installed.
<br/><br/>
Embedding a font guarantees it will be available to the PDF viewer, but increases the
file size of the document. TrueType font glyphs can be subset (meaning only the characters
that are used are embedded), which reduces the file size. This is generally a good idea,
and TrueType fonts are subset by default when embedded.
<br/><br/>
When creating an embedded OpenType font, the user has to decide whether to embed it
using 1 or 2 bytes per glyph. Using a single byte can save space, but limits the font to
displaying only 255 different glyphs. This is more than enough for almost every
language except Chinese, Japanese, Korean, although we generally recommend that when
embedding an OpenType font, 2 bytes per glyph are used for all non-western European
languages, as this is more compatible with older PDF viewers and also some
text-extraction tools.
<br/><br/>
PDF does not have a native concept of <b>bold</b> or <i>italic</i>. Instead,
each variation is treated as a completely separate font (most operating
systems and word-processors work this way too, but shield this fact from the
user). This means that to italicize a single word, you need to access two
different fonts - which means even larger files when you're using embedded fonts.
<br/><br/>
So how do you use one of these fonts? In the <tt>HelloWorld</tt> example
earlier, you saw how to access one of the built in fonts. Here's how you use a TrueType
font in a document.
</p>
<pre id="exampleOpenType" class="example">
1. public void showText(PDFPage page)
2. throws IOException
3. {
4. <b>PDFFont myfont = new OpenTypeFont(new File("myfont.ttf"), 1);</b>
5. PDFStyle mystyle = new PDFStyle();
6. mystyle.setFont(myfont, 11);
7. page.setStyle(mystyle);
8. page.drawText("This is a TrueType font", 100, 100);
9. } </pre><p class="caption">Example 4 - Using an OpenType font</p>
<p>
The only different between the earlier version and this one is line 4.
<br/><br/>
One of the unique features of this library is that the full range of characters from each
font can be used. Traditionally in PDF documents, authors had to choose an
<i>encoding</i>, which gave them access to a certain number of characters but no more. If
your font had characters that weren't in this predefined set, tough. We work around that
internally, so that the full range of characters from each font can be accessed easily -
essential for languages that use characters outside the basic US-ASCII range. As you would
expect for a Java library, we use the Unicode standard to access each character. To print
the Euro character (€), you would use a line like
<tt><nobr>page.drawText("Hello, \u20AD world");</nobr></tt> in your code. If the font has
the correct symbol, the character will be displayed.
</p>
<h1 id="FormattingText">Formatting Text</h1>
<p>
Up until version 1.2 of the library, the way to place text on the page was via the
<code>beginText</code>, <code>drawText</code> and <code>endText</code> methods, the simplest
variation of which you've already seen in the previous examples. While effective, these methods
were limited - you couldn't mix text and graphics in a single paragraph, and the only way to
calculate the height of a paragraph of text was to draw it first, find out how much space it
took then discard it.
</p>
<p>
To remedy these problems, in version 1.2 the new <code>LayoutBox</code> class was added,
which gives a lot more control at the expense of perhaps being a little more complicated.
As they're quite different to use, we'll cover both techniques separately
</p>
<h2 id="textDrawText">Simple text formatting using the drawText method</h2>
<pre id="exampleFormatText" class="example">
1. public void formatText(PDFPage page)
2. {
3. PDFStyle plain = new PDFStyle();
4. plain.setFillColor(Color.black);
5. plain.setTextAlign(PDFStyle.TEXTALIGN_JUSTIFY);
6. plain.setFont(new StandardFont(StandardFont.HELVETICA), 11);
7.
8. PDFStyle bold = (PDFStyle)plain.clone();
9. bold.setFont(new StandardFont(StandardFont.HELVETICABOLD), 11);
10.
11. <b>page.beginText(50,50, page.getWidth()-50, page.getHeight()-50);</b>
12. page.setStyle(plain);
13. <b>page.drawText("This text is in ");</b>
14. page.setStyle(bold);
15. <b>page.drawText("Helvetica Bold.");</b>
16. <b>page.endText(false);</b>
17. } </pre><p class="caption">Example 5 - Simple text using the drawText method</p>
<p>
For text layout, the library uses the concept of a <i>box</i> - a rectangle on the
page containing a block of text. Text within this block can be written in different
styles, and can be left or right aligned, centered or justified. You can even mix
TrueType, Type 1 and the Standard fonts on the same line.
<br/><br/>
The example above shows some of the method calls used to draw the text on the page. The
<tt>beginText</tt> method is the most important, as it defines the rectangle in which to
place the text. It takes the X and Y positions of two opposite corners of the rectangle -
in this example the entire page is used, less a 50 point margin.
<br/><br/>
Once <tt>beginText</tt> is called, the <tt>drawText</tt> method can be called as many
times as necessary to place the text on the page, interspersed with calls to
<tt>setStyle</tt> as required.
<br/><br/>
To end the text block, call the <tt>endText</tt> method. This takes a single boolean
parameter, which determines whether to justify the final line of text <i>if</i> the current
text alignment is justified. Nine times out of ten, this will be set to false.
</p>
<h3>The End of the Line</h3>
<p>
When a line of text hits the right margin, it's wrapped to the next line. Exactly where it
is wrapped is open to debate. We've chosen to follow the guidelines set down by the
Unicode consortium as closely as possible, which generally speaking means lines are
wrapped at spaces or hyphens, but words themselves are not split. Japanese, Chinese and
Korean follow a different set of rules, which means that words can be split just about
anywhere (with a few exceptions to do with small kana and punctuation). For more control
over this, we need to look at using some of the <a href="#Unicode">control characters</a>
defined in the Unicode specification.
</p>
<h3>The End of the Page</h3>
<p>
When the text box defined by the <tt>beginText</tt> method is full, no further text will
be displayed. Instead, it's held in an internal buffer waiting for you to tell the library
what to do with it. You can tell when the box is full by checking the return value of the
<tt>drawText</tt> method. Normally this returns the number of lines displayed (in points),
but if it returns <tt>-1</tt> that indicates that the box is full. However, be warned -
one of the major reasons we moved to the <code>LayoutBox</code> classes is because
measuring text this way wasn't accurate enough for complicated layouts. If your text
is going to wrap to the next column or page, we <b>strongly</b> recommend you use the
<code>LayoutBox</code> class instead.
</p>
<h2 id="textLayoutBox">Advanced text formatting using the LayoutBox class</h2>
<p>
The <code>LayoutBox</code> class was added in version 1.2 to remedy several deficiencies
with the existing text-layout model. While able to do everything that the
<code>drawText</code> method can do, it adds several new features:
</p>
<ul>
<li>mix images and other blocks with the text</li>
<li>determine the size and position of a phrase in the middle of a paragraph</li>
<li>determine the height of the text before it's printed to the page</li>
<li>better layout control when adjusting the font size over a line</li>
</ul>
<p>
First, a simple example, which is almost identical to the last one we demonstrated.
</p>
<pre id="exampleTextLayoutBox" class="example">
1. public void formatText(PDFPage page)
2. {
3. Locale locale = Locale.getDefault();
4.
5. PDFStyle plain = new PDFStyle();
6. plain.setFillColor(Color.black);
7. plain.setTextAlign(PDFStyle.TEXTALIGN_JUSTIFY);
8. plain.setFont(new StandardFont(StandardFont.HELVETICA), 11);
9.
10. PDFStyle bold = (PDFStyle)plain.clone();
11. bold.setFont(new StandardFont(StandardFont.HELVETICABOLD), 11);
12.
13. <b>LayoutBox box = new LayoutBox(page.getWidth()-100);</b>
14. <b>box.addText("This text is in ", plain, locale);</b>
15. <b>box.addText("Helvetica Bold.", bold, locale);</b>
16. <b>page.drawLayoutBox(50, page.getHeight()-50);</b>
17. } </pre><p class="caption">Example 6 - Text using the LayoutBox class</p>
<p>
We say "almost identical" to the previous example, because there's one subtle difference,
and that's the <i>anchor point</i> for the two different text methods is different. With
the <code>beginText</code>, the coordinates you give the method are the position of the
<b>baseline</b> of the first line of text. The first line of text will mostly be displayed
above this point. With the <code>drawLayoutBox</code> method, the coordinate you give it
is the <b>top-left</b> corner of the box, equivalent to the top of the first line of text.
This allows better control when mixing images or various different size of fonts on the
same line.
</p>
<table width="100%" page-break-inside="avoid" id="figureTextAnchor">
<tr>
<td height="100" border="1" padding="5" margin-right="10">
<p position="absolute" margin="0" line-height="100%" background-color="yellow" left="40" top="0" font-size="50pt">Sample</p>
<div position="absolute" top="40" background-color="red" width="100%" height="1"/>
<circle position="absolute" left="40" top="40.5" border="0" background-color="red" radius="2"/>
<p position="absolute" color="red" font-size="8pt" align="right" left="0" top="30" width="35">x,y</p>
</td><td height="100" border="1" padding="5">
<p position="absolute" margin="0" line-height="100%" background-color="yellow" left="40" top="40" font-size="50pt">Sample</p>
<div position="absolute" top="40" background-color="red" width="100%" height="1"/>
<circle position="absolute" left="40" top="40.5" border="0" background-color="red" radius="2"/>
<p position="absolute" color="red" font-size="8pt" align="right" left="0" top="30" width="35">x,y</p>
</td>
</tr>
<tr>
<td><p class="caption">Figure 1a - Positioning using <code>beginText</code></p></td>
<td><p class="caption">Figure 1b - Positioning using <code>drawLayoutBox</code></p></td>
</tr>
</table>
<h3 id="textLayoutBoxImages">Mixing text and images</h3>
<p>
Now we've got the basics covered, we'll show you some of the more interesting tricks
you can do with the <code>LayoutBox</code> class. First, and probably simplest, is placing
an image in the middle of the text.
</p>
<pre class="sexample" id="exampleTextInlineImage">
1. LayoutBox box = new LayoutBox(width);
2. box.addText("This text is before the image ", mystyle, locale);
3. <b>LayoutBox.Box image = box.addBoxInline(imgwidth, imgheight, PDFStyle.TEXTALIGN_BASELINE);</b>
4. box.addText(" and this text is after.", mystyle, locale);
5.
6. page.drawLayoutBox(x, y);
7. page.drawImage(image, <b>x+box.getLeft()</b>, <b>y+box.getLeft()</b>, <b>x+box.getRight</b>, <b>y+box.getBottom()</b>);
</pre>
<p class="caption">Example 7 - Mixing Text and Images in a LayoutBox</p>
<p>
As you can see here, we call the <code>LayoutBox.addBoxInline</code> method to place a
"box" in the middle of the paragraph. This method, like all the other <code>add...</code>
methods in the <code>LayoutBox</code> class, returns a <code>LayoutBox.Box</code> object
which can be used to determine the position of the rectangle relative to the position of
the <code>LayoutBox</code>. Here we use those coordinates to draw an image on the page,
but it would be just as easy to, say, fill the rectangle with a color.
Here's what the output of this example could look like.
</p>
<p align="center" border="1">
This text is before the image
<img display="inline" src="resources/certshot2.png" dpi="600"/>
and this text is after.
</p>
<p>
Two further things to point out before we move on. First, the last parameter to the
<code>addBoxInline</code> method controls the <i>vertical alignment</i> of the image,
relative to the rest of the text. We'll cover more on vertical-alignment in a minute. The
second thing is that there's an even easier way to draw an image than the method shown
above - use the <code>LayoutBox.Box.setImage</code> method. This convenient shortcut saves
you from having to call the <code>drawImage</code> method yourself, although it's limited
to working with images.
</p>
<h3 id="textLayoutBoxText">Text positions - using LayoutBox.Text class</h3>
<p>
The next example shows how to use the boxes returned from <code>addText</code> to draw a
colored background to a piece of text.
</p>
<pre class="sexample" id="exampleTextTwin">
1. PDFStyle background = new PDFStyle();
2. background.setFillColor(Color.blue);
3.
4. LayoutBox box = new LayoutBox(width);
5. box.addText("The following phrase will be drawn on ", mystyle, locale);
6. <b>LayoutBox.Text text = box.addText("a blue background", mystyle, locale);</b>
7. box.addText(", but now we're back to normal.", mystyle, locale);
8. <b>box.flush();</b> <i>// Important, or the last line may not be positioned!</i>
9.
10. page.setStyle(background);
11. do {
12. page.drawRectangle(<b>x+text.getLeft()</b>, <b>y+text.getLeft()</b>, <b>x+text.getRight</b>, <b>y+text.getBottom()</b>);
13. <b>text=text.getNextTwin();</b>
14. } while (text==null);
15. page.drawLayoutBox(x, y);
</pre><p class="caption">Example 8 - Setting the background behind the text</p>
<p>
If you take a close look at this example you'll see it's almost identical to the previous
example, with the exception of the <code>do/while</code> loop. Why is it there? The
answer lies in how text is positioned in the <code>LayoutBox</code>. When you add a piece
of text to the box, unless you call the <code>addTextNoBreak</code> method or otherwise
have good reason to assume the text won't be split over more than one line, you have to
allow for this possibility. The <code>LayoutBox.Text.getNextTwin()</code> method allows you
to cycle through the one or more <code>LayoutBox.Text</code> objects which represent the
phrase of text on the page, until the method returns <code>null</code> - indicating all
the boxes have been returned. If you're using the LayoutBox class and want to turn some of the
text into hyperlinks, this is the way to do it.
</p>
<h3 id="textLayoutBoxVertical">Vertical positioning in a LayoutBox line</h3>
<p>
Prior to version 1.2 there was only very basic support for mixing different sized text on
a single line. The <code>LayoutBox</code> class adds full, Cascading Style-Sheet style support
for vertical alignment. When mixing elements of different height on the page, you need to be
aware of what options are available to help with positioning them.
</p>
<p>
Before we continue, there are two definitions we need to make. The <b>Text Box</b> is a
box equivalent to the size of the text itself. This may be the same as or smaller than the
<b>Line Box</b>, which is the box equivalent to the size of the entire line. A line box is
always sized so that it fits the largest text box in the line. In the example below, the
line box is in yellow, the larger text-box is in green and the smaller of the two
text-boxes is shown in orange.
</p>
<table align="center" cellpadding="4" cellmargin-right="8" cellborder="1" id="figureTextVerticalAlign">
<tr>
<td>
<p line-height="100%" background-color="yellow" font-size="24pt">
<span background-color="lightgreen">Large</span>
<span font-size="10pt" background-color="orange" vertical-align="top"> Top </span></p>
</td>
<td>
<p line-height="100%" background-color="yellow" font-size="24pt">
<span background-color="lightgreen">Large</span>
<span font-size="10pt" background-color="orange" vertical-align="middle">Middle</span></p>
</td>
<td>
<p line-height="100%" background-color="yellow" font-size="24pt">
<span background-color="lightgreen">Large</span>
<span font-size="10pt" background-color="orange" vertical-align="baseline">Baseline</span></p>
</td>
<td>
<p line-height="100%" background-color="yellow" font-size="24pt">
<span background-color="lightgreen">Large</span>
<span font-size="10pt" background-color="orange" vertical-align="bottom">Bottom</span></p>
</td>
</tr>
</table>
<p class="caption">Figure 2 - Vertical alignment examples</p>
<p>
This example shows the four different options for vertical alignment within a line box.
<b>Top</b> places the top of the text box at the top of the line box. <b>Middle</b> places the
middle of the text box at the middle of the line box. <b>Baseline</b>, the default, places the
baseline of the text box at the baseline of the line box. Finally, <b>bottom</b> places the
bottom of the text box at the bottom of the line box.
</p>
<p>
The same rule applies to boxes added using the <code>addBoxInline</code> method. In the
<a href="#exampleTextInlineImage">image example</a> above we use the
<code>PDFStyle.TEXTALIGN_BASELINE</code> method to place the image, although as the image
was the largest item on the line it had no effect. If the box representing the image is
smaller than the line box however, the last parameter to <code>addBoxInline</code> has the
same sort of effect as with the text demonstrations above.
</p>
<p>
The height of each text box depends on both the size of the font used, and it's
<i>leading</i> - white space between lines. Each font has a preferred leading, which is
set by the font author. This can be retrieved by the
<code>PDFFont.getDefaultLeading</code> method. The line height can then be set as a
multiple of this value by calling the <code>PDFStyle.setTextLineSpacing</code> method.
Passing in a value of <code>1.0</code> results in each line of text using the default
leading, whereas a value of <code>2.0</code> would double it, and so on. Leading is always
evenly distributed, half above and half below the text.
</p>
<h3 id="textLayoutBoxFloating">Floating boxes</h3>
<p>
You've seen how to add images in the middle of a paragraph, but there's one more common
type of placement - known as <i>float positioning</i>. This allows a paragraph of text to
wrap around a rectangle. We've already used this style of positioning a few times in this
document - see the <a href="#noteStandardFonts">Standard Fonts note</a> on page
<pagenumber idref="noteStandardFonts"/> for an example.
</p>
<p>
Boxes can be "floated" to the left or right of a paragraph - simply call the
<code>addBoxLeft</code> or <code>addBoxRight</code> method to choose which. The top of the
box will be placed either on the current line or the first clear line, depending on the
clear flags (more in a minute), and any further text will wrap around it until the text
grows beyond the height of the box. This is easier to describe with an example.
</p>
<pre class="sexample" id="exampleTextFloat">
1. PDFStyle background = new PDFStyle();
2. background.setFillColor(Color.blue);
3.
4. LayoutBox box = new LayoutBox(width);
5. box.addText("The following text will be drawn ", mystyle, locale);
6. <b>LayoutBox.Box box = box.addBoxRight(50, 50, LayoutBox.CLEAR_NONE);</b>
7. box.addText("around the box to the right. When it grows beyond that box\
it will automatically fill the width of the line", mystyle, locale);
8.
9. page.drawLayoutBox(x, y);
10. page.drawRectangle(x+text.getLeft(), y+text.getLeft(), x+text.getRight, y+text.getBottom());
</pre><p class="caption">Example 9 - Text floating around a box to the right</p>
<p requote="true" text-align="justify" border="1" font-size="22pt"
padding="4" margin-bottom="0pt">
<div float="right" width="100" height="50" border="1" margin-left="10" background-color="blue"/>
"The following text will be drawn around the box to the right. When it grows beyond that box, it will automatically fill the width of the line."
</p>
<p class="caption">Figure 3 - Text flowing around a floating box</p>
<p>
The <code>CLEAR_NONE</code> flag effectively says "it doesn't matter if another box is already
floating to the right - in that case, place this box next to it" - although in this example
there's only one floating box, so it has no measurable effect. The other alternative
is to say that this box <i>must</i> be placed flush on the right margin - if another
floating box is already there, it will position itself below that one. There are all
sorts of variations on this theme, and we won't describe all of them. Instead, we'll
leave you with an example showing the sort of layout that this class is capable of.
</p>
<pre id="exampleTextFloatComplex" class="example">
1. <span background-color="yellow"> </span>box.addBoxRight(50, 50, LayoutBox.CLEAR_RIGHT);
2. <span background-color="orange"> </span>box.addBoxRight(50, 50, LayoutBox.CLEAR_RIGHT);
3. <span background-color="lightgreen"> </span>box.addBoxRight(50, 50, LayoutBox.CLEAR_NONE);
4. box.addText("Text text ...", mystyle, locale);
5. <span background-color="pink"> </span>box.addBoxLeft(50, 50, LayoutBox.CLEAR_NONE);
6. <span background-color="lightblue"> </span>box.addBoxLeft(50, 50, LayoutBox.CLEAR_NONE);
7. <span background-color="khaki"> </span>box.addBoxLeft(50, 50, LayoutBox.CLEAR_NONE);
8. <span background-color="salmon"> </span>box.addBoxLeft(50, 50, LayoutBox.CLEAR_LEFT);
9. box.addText("More more ...", mystyle, locale);
</pre>
<p text-align="justify" border="1" font-size="12pt" padding="4" margin-bottom="0pt">
<div float="right" clear="right" width="40" height="40" border="1" margin="2" background-color="yellow"/>
<div float="right" clear="right" width="40" height="40" border="1" margin="2" background-color="orange"/>
<div float="right" clear="none" width="40" height="40" border="1" margin="2" background-color="lightgreen"/>
Text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text text
<div float="left" clear="none" width="40" height="40" border="1" margin="2" background-color="pink"/>
<div float="left" clear="none" width="40" height="40" border="1" margin="2" background-color="lightblue"/>
<div float="left" clear="none" width="40" height="40" border="1" margin="2" background-color="khaki"/>
<div float="left" clear="left" width="40" height="40" border="1" margin="2" background-color="salmon"/>
More more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more
</p>
<p class="caption">Figure 4 - Things you can do with the "clear" flag</p>
<h1 id="AdvancedText">Advanced text layout features</h1>
<h2 id="Quotes">Quotes</h2>
<p>
The <tt>requote</tt> method in the <tt>PDFFont</tt> class can be used to substitute the
normal single (') and double (") quote characters into nicer
looking glyphs - turning "a test" into “a test”, „ein test“,
”en prøve” or whatever is appropriate for the specified locale.
</p>
<p>
<div float="left" whitespace="nowrap" width="27%" class="note" id="noteKerning">
<p padding="0" margin="0">With kerning</p>
<p padding="0" margin="0" font="Times" font-style="normal" font-size="26">AWAW</p>
<p padding="0" margin="0">Without kerning</p>
<p padding="0" margin="0" font="Times" font-style="normal" font-size="26">A‌W‌A‌W</p>
<p padding="0" margin="0">Ligatures, with & without</p>
<p padding="0" margin="0" margin-bottom="-2" font="Times" font-style="normal" font-size="26">fi f‌i</p>
</div>
<h2 id="Kerning">Kerning, Spacing and Ligatures</h2>
Most good quality fonts have a <i>kerning table</i>, which allows for the spaces
between letters to be adjusted for improved appearance - as you can see, a sequence
of A's and W's without kerning look too far apart. Another way to improve the
appearance of text is with ligatures - a single shape representing two or more joined
characters. They're not too common in Latin scripts, but in languages like Arabic they're
essential. Throughout the library, variable-width fonts have kerning and
ligatures applied automatically, unless they're inhibited using the
<a href="#Unicode">Unicode Control character</a> "zero-width non-joiner".
<br/><br/>
For control over spacing between letters, there are several options. First is the
method we'd generally recommend because we feel it gives the best results - setting
the <i>justification ratio</i>.
<br/><br/>
The <code>setJustificationRatio</code> method of the <tt>PDFStyle</tt> class allows you to
choose where to add the extra whitespace required to justify a short line of text. A value
of 0 means extend spaces between words, for a result like
<span font="bold Helvetica" whitespace="pre">THREE SHORT WORDS</span>,
whereas a value of 1 means extend the spaces between letters like this:
<span font="bold Helvetica" whitespace="pre">T H R E E S H O R T W O R D S</span>.
The default is 0.5, i.e. somewhere in the middle, and gives good results (this document
is formatted using the default value). Kashida justification, required for justifying
Arabic script, is not supported in this release.
<br/><br/>
Another option is track kerning, which allows you to manually squeeze or expand
the space between letters. This is done using the <code>setTrackKerning</code>
method in the <code>PDFStyle</code> class. The effect is equivalent to moving every
letter together or apart by a fixed amount.
<br/><br/>
The final option is to use the Unicode spacing characters - U+2000 to U+200A. These only
work with the proportional Standard Fonts, i.e. Helvetica and Times. These spacing glyphs
are legacies of the pre-electronic typesetting days, when spacing was done manually by
inserting small spacing blocks between each letter on the press. Although not as useful
today, they are an option which some users may prefer. Simply insert them between letters
in the same way as a normal space character.
</p>
<h2 id="TextMeasurement">Text measurement and positioning</h2>
<p>
In some situations it's required that the size of the text is known beforehand. This is
easily done with the <tt>getTextLength</tt> method and friends from the <tt>PDFStyle</tt>
class. They return the exact left, right, top and bottom of the specified line of text in
points, so the size of the text is known beforehand. For even more precision, the methods
like <tt>getAscender</tt> in the <tt>PDFFont</tt> class allow you to adjust the position
of the text accordingly.
</p>
<h1 id="International">International support</h1>
<p>
For many of the worlds languages, provided an appropriate font is used the library will
work out-of-the-box. The standard 14 fonts cover (to the best of our knowledge) English,
German, French, Spanish, Norwegian, Swedish, Danish, Finnish, Italian, Portuguese, Catalan
(although the "L with dot" character is missing), Basque, Dutch (no "ij" ligature), Albanian,
Estonian, Rhaeto-Romance, Faroese, Icelandic, Irish, Scottish, Afrikaans, Swahili, Frisian,
Galician, Indonesian/Malay and Tagalog. With an appropriate embedded font, most other languages
will work, although remember that Java up to and including version 1.4 and Acrobat up to 6.0 is
limited to the Basic Multilingual Plane of Unicode - the first 65,536 characters, or 2 bytes per
glyph.
</p>
<p>
Arabic, Hebrew and Yiddish are fully supported as of version 1.1 of the library, which
implements the full <a href="http://www.unicode.org/unicode/reports/tr9">Unicode
bidirectional algorithm</a> version 3.1 - although the complete range of Arabic ligatures
is not yet implemented, the number that are there should cover most cases. The Unicode
directional override characters are supported as per that specification.
</p>
<p>
Japanese, Chinese (simplified and traditional) and Korean are also supported as of version 1.1,
although in horizontal writing mode only. To display text in these languages,
an OpenType font can be embedded with 2 bytes per glyph. This will probably result in a
very large document however, as several hundred glyphs would typically be used. There is
another option - Adobe have defined several "standard" fonts which are available with the
localized versions of it's viewers, or as separate language packs
<a href="http://www.adobe.com/products/acrobat/acrrasianfontpack.html">downloadable</a> from
their website.
<br/><br/>
These fonts can be used via the <tt>StandardCJKFont</tt> class, which is similar to the
<tt>StandardFont</tt> class for latin-based scripts - although if the viewer doesn't have the
appropriate font installed, all they'll see is a request to download it. Line breaking for
these languages follows the recommendations laid out in the Unicode 3.1 specification, but the
zero-width space characters can be used to override this. Since version 1.2.1 the Hong Kong
Supplementary Character Set (HKSCS) is supported in the MSung font, although you'll need Acrobat
5.0 or later to display these.
<br/><br/>
Acrobat 6.0 and Java 1.5 both introduced the ability to go beyond the Basic Multilingual Plane (BMP).
This is done using UTF-16, which uses <i>low and high surrogates</i> and so does not require the
basic "character" to be expanded beyond 16 bits. This is fully supported in the PDF library since
2.2.6. Additionally, Java 1.5 is <i>not</i> required - using Java 1.3 it is quite possible to create
a String containing the appropriate low and high surrogate characters, create a PDF from it using
an appropriate font and have it display correctly in Acrobat 6.0.
National standards using this range include HKSCS-2001 and JISX0213:2004, both of which are supported
in Acrobat 6.0 with the "MSung" and "HeiSeiMin" fonts.
</p>
<p>
A word on GB18030-2000. This is the standard required by the Chinese Government, and covers
latin, simplified and traditional Chinese, Japanese, Korean, cyrillic and Arabic scripts, as well as
less well known ones like, Yi, Mongolian and Uygur. The PDF library <i>can</i> support this standard,
although not with one font (as you might expect). Our suggestion for those requiring GB18030-2000 support
is to use the <code>PDFStyle.addBackupFont</code> method to create a style with a primary font and a
number of backups to be used as required. Typically you would use the <code>StandardFont</code> Times,
the <code>StandardCJKFonts</code> STSong, MSung, HeiSeiMin and HYSMyeongJo, then would have one or more
OpenType fonts covering Arabic, cyrillic and the lesser used chinese dialects.
</p>
<p>
The following languages have poor or non-existent support.
</p>
<ul>
<li>
Thai, Khmer and Myanmar should work fine, but the rules for line-breaking require
analysis of the words being printed, which we can't do. This means that line-breaking will
have to be done manually, by inserting spaces or zero-width spaces where
appropriate.
</li>
<li>
We haven't worked on the Devenagari scripts - Hindi, Bengali and friends - owing to the difficulty
in finding a decent font with the correct Unicode encoding, and because we don't know anyone that
writes it well enough to tell us whether we've got it right or not.
</li>
<li>
Urdu, with it's right-to-left diagonal baseline, is unlikely to be supported in the near
future, although if a horizontal baseline is acceptable it should work fine.
</li>
<li>
Mongolian and Tibetan both have unusual line-breaking rules, which we haven't attempted to
implement. This can be done manually like for Thai, above. Vertical display of traditional
Mongolian text is not supported, nor is it likely to be.
</li>
<li>
Any other languages requiring ligatures to display correctly (other than Arabic and
Armenian) are not currently supported, probably because we don't know about them.
</li>
</ul>
<p>
The <tt>setLocale</tt> method of the <tt>PDF</tt> class is important with multi-lingual
documents, as it determines the primary text direction of a document, the default text
alignment (right-aligned for Arabic and Hebrew locales), the style of quote-substitution
to use and various other aspects of the display. It defaults to the system Locale, so
generally it's already correct - but just in case it can be set and re-set as many times
as needed. The locale being used when the PDF is written is considered to be the locale of
the document as a whole, and the language flag in the PDF is set accordingly.
</p>
<h2 id="CharacterAvailable">Is this character available?</h2>
<p>
How do you know if a certain character is available in the font you're using? One way is
to create the document, and look for a line resembling <tt>WARNING: Skipping unknown
character '?' (0x530)</tt> printed to <tt>System.err</tt>. Of course, by the time you've
got this information it's too late, so a better way is to call the <tt>isDefined</tt>
method of the <tt>PDFFont</tt> you're using, which returns true if the character is
defined.
</p>
<p>
Something to remember if you're using non-embedded fonts (particularly the
<tt>StandardCJKFont</tt> fonts) is that just because a character is defined on your local
copy of the font, doesn't mean that the character is defined in the version on the viewers
machine.
</p>
<h1 id="Unicode">Unicode</h1>
<p>
The <a href="http://www.unicode.org">Unicode</a> specification is a universal encoding for
every character in every language. It's a work in progress, which means that new
characters are being added all the time. All Java strings are automatically in Unicode,
and the library supports it too - which means it's easy to mix characters from many
languages in a single phrase.
</p>
<p>
Any character from the entire Unicode code range can be added to the document, without
having to worry about codepages, encodings and various other difficulties common when
using Unicode in PDF - the library takes care of it all internally, and provided the font
has the character defined, it will be displayed.
</p>
<p>
As well as defining a list of characters, the Unicode specification goes further and
defines various rules for layout of text, such as the bi-directional algorithm (how to
handle mixed left-to-right and right-to-left text on a single line), rules for when to add
a line break, and so on. Some of the code-points in the specification are control
characters which affect these algorithms, in the same way that the ASCII code 9 means
"horizontal tab".
</p>
<p>
The library supports most of these control codes, which can be included in any text
displayed on the page to control exactly how the page is laid out.
</p>
<table class="defns" id="tableUnicodeControlChars">
<tr>
<td>U+00A0</td>
<td>Non-Breaking Space</td>
<td>
The same as a regular space character, but prevents the words on either side being
separated by a line break
</td>
</tr>
<tr>
<td>U+00AD</td>
<td>Soft Hyphen</td>
<td>
Inserted into a word to indicate that the word <i>may</i> be split at that point. If the
word is actually split, a hyphen is displayed, otherwise this character is invisible
</td>
</tr>
<tr>
<td>U+200B</td>
<td>Zero-Width Space</td>
<td>
Inserted into a word to indicate that the word <i>may</i> be split at that point.
Regardless of whether the word is split or not, this character is invisible
</td>
</tr>
<tr>
<td>U+2011</td>
<td>Non-Breaking Hyphen</td>
<td>
Identical to a hyphen, but prevents the characters on either side from being split.
</td>
</tr>
<tr>
<td>U+FEFF</td>
<td whitespace="nowrap">Zero-Width Non-Breaking Space</td>
<td>
Inserted into a word to prevent the word being split or hyphenated at that point, or
around characters which would otherwise be a potential break-point.
</td>
</tr>
<tr>
<td>U+200C</td>
<td>Zero-Width Non-Joiner</td>
<td>
Inserted into a word to indicate that no
ligature should be formed between these two letters. Mostly used in Arabic language
scripts, we also use it to prevent the "f" and the "i" joining as a ligature in the
example on the previous page, and to prevent kerning.
</td>
</tr>
<tr>
<td>U+200D</td>
<td>Zero-Width Joiner</td>
<td>
Inserted into a word to indicate that the characters <i>should</i> be replaced with a
ligature. Currently has no effect.
</td>
</tr>
<tr>
<td whitespace="nowrap">U+200E, U+200F,<br/>U+202A - U+202E</td>
<td>Directional Indicators</td>
<td>
Inserted into a phrase to control text direction for bidirectional text. These
function as described in the Unicode bidirectional algorithm.
</td>
</tr>
<tr>
<td>U+2044</td>
<td>Fraction Slash</td>
<td>
Not strictly a control character, when placed between two numbers this slash results
in the appropriate fraction being substituted - so <tt>page.drawText("1\u20442")</tt>
displays as "1⁄2". In version 1.1 this will only work if the appropriate
fraction is defined in the font.
</td>
</tr>
<tr>
<td>U+2028, U+2029</td>
<td whitespace="nowrap">Line and Paragraph Separators</td>
<td>
Unicodes attempt at solving the age-old "CR+LF, CR or LF" problem was to add two new
characters which are to be unambiguous in their meaning. There is no advantage to
using these - the library regards both of these as a normal newline (whatever is
produced by "\n" on your system).
</td>
</tr>
</table>
<p class="caption">Table 3 - Unicode control characters</p>
<h1 page-break-before="always" id="BitmapGraphics">Graphics</h1>
<h2>Bitmap Images</h2>
<pre id="exampleShowImage" class="example">
1. public void showImage(PDFPage page)
2. throws IOException
3. {
4. PDFImage img = new PDFImage(new FileInputStream("myimage.jpg"));
5. int width = img.getWidth();
6. int height = img.getHeight();
7. page.drawImage(img, 100, 100, width, height);
8. } </pre><p class="caption">Example 10 - Displaying an image</p>
<p>
Adding bitmap images to the document can be done with a couple of lines - the first loads
the image, the second places it on the page. Images can be read directly from a file (the
library can parse JPEG, PNG, GIF, TIFF and PNM images) or loaded from a <tt>java.awt.Image</tt>.
This gives enormous flexibility - bitmaps can easily be created using normal
<tt>java.awt</tt> methods, or an extension library like <a
href="http://java.sun.com/products/jimi">Sun's Jimi library</a> can be used to load PCX
images, Adobe Photoshop™ files and many other formats.
</p>
<p>
When embedding a bitmap image, there are a few points you should remember.
</p>
<ol>
<li>
Transparency is poorly supported in PDF prior to Acrobat 5.0 - earlier versions were
limited to "masked" transparency (as used in GIF and 8-bit PNG images) where a single
color can be flagged as transparent. Additionally, PostScript limitations in
Acrobat 4.0 and earlier may cause large images to be rendered without transparency
when printed in Acrobat 4.0 - see the API documentation for more info.
</li>
<li>
Most computer monitors have a resolution of 72 (Windows) or 96 (Macintosh)
dots-per-inch, which means a 200x200 pixel bitmap will take between 2 and 2.8 inches on
the screen. When printing an image to a high resolution printer however, the minimum you
can get away with is probably around 200dpi for a color image and 300dpi for black and
white, otherwise the image is going to start to get "blocky". Depending on the
type of image you're embedding you should generally use bitmaps <i>at least</i> 3 times
the size you would use for on-screen viewing if you want to print the PDF.
</li>
</ol>
<p>
Here's an example of what we mean. The first logo is embedded at 200 dpi, the second is at
72dpi. Print the document out or zoom in for a closer look, and see the difference.
</p>
<table width="100%">
<tr>
<td align="left">
<img src="resources/logobig.jpg" width="264" height="95"/>
</td>
<td width="50%" align="right">
<img src="resources/logosmall.jpg" width="264" height="95"/>
</td>
</tr>
</table>
<p>
The DPI of the image in the document is the number of inches the bitmap takes up, divided
by the number of pixels in the bitmap. So a 200 pixel wide bitmap sized to take up 72
points (1 inch) in the document has a resolution of 200dpi. All image formats except GIF
can specify the DPI of the image (if it's not specified it defaults to 72dpi), so the
example above displays the image at the point-size the artist intended. For more control,
it's possible to extract the X and Y resolution of the image using the
<code>getDPIX()</code> and <code>getDPIY()</code> methods.
</p>
<pbr/>
<h2 id="LineGraphics">Vector Graphics</h2>
<p>
It's also possible to draw "line-art" style images directly into the PDF. Here's an
example that draws a circle of radius 100 in the center of the page, filled with blue
stars on a red background and with a black border.
</p>
<pre id="exampleDrawCircle" class="example">
1. public void drawCircle(PDFPage page)
2. {
3. PDFStyle style = new PDFStyle();
4. style.setLineColor(Color.black);
5. style.setFillColor(new PDFPattern("Star",0,0,50,50,Color.red,Color.blue));
6. page.setStyle(style);
7.
8. <b>page.drawCircle(page.getWidth()/2, page.getHeight()/2, 100);</b>
9. } </pre><p class="caption">Example 11 - Drawing a circle</p>
<p>
Not terribly difficult. As well as drawing circles, there are several other shapes
that can be easily drawn.
</p>
<table width="100%" padding="0" margin-bottom="10">
<tr>
<td height="80" align="center" class="imgexample" id="methodPDFPage_drawEllipse">
<p class="imgexamplehead">drawCircle / drawEllipse</p>
<ellipse width="100%" height="100%" margin="10" border-color="red" background-color="blue"/>
</td>
<td height="80" align="center" class="imgexample" id="methodPDFPage_drawLine">
<p class="imgexamplehead">drawLine</p>
<shape width="100%" height="100%" border-color="red" border="2" margin="10">
<shapepath>
<lineto x="100%" y="100%"/>
</shapepath>
</shape>
</td>
<td height="80" align="center" class="imgexample" id="methodPDFPage_drawArc">
<p class="imgexamplehead">drawArc</p>
<shape width="100%" height="100%" border-color="red" border="2" margin="10">
<shapepath>
<arcto width="200%" height="200%" startangle="0" endangle="90"/>
</shapepath>
</shape>
</td>
</tr>
<tr>
<td height="80" align="center" class="imgexample" id="methodPDFPage_drawRectangle">
<p class="imgexamplehead">drawRectangle</p>
<div width="100%" height="100%" margin="10" border-color="red" background-color="blue"/>
</td>
<td height="80" align="center" class="imgexample" id="methodPDFPage_drawRoundedRectangle">
<p class="imgexamplehead">drawRoundedRectangle</p>
<div width="100%" height="100%" margin="10" border-color="red" corner-radius="10" background-color="blue"/>
</td>
<td height="80" align="center" class="imgexample" id="methodPDFPage_drawPolygon">
<p class="imgexamplehead">drawPolygon</p>
<shape width="100%" height="100%" border-color="red" background-color="blue" margin="10">
<shapepath>
<lineto x="20%" y="20%"/>
<lineto x="40%" y="0%"/>
<lineto x="60%" y="20%"/>
<lineto x="80%" y="0%"/>
<lineto x="100%" y="20%"/>
<lineto x="100%" y="100%"/>
<lineto x="0%" y="100%"/>
<lineto x="0%" y="0%"/>
</shapepath>
</shape>
</td>
</tr>
</table>
<p>
Remember that every shape except the lines or the arcs can be drawn as outlines, solid
or both - it <a href="#noteOutlineSolid?zoom=fill">depends</a> on whether a fill, a
line color or both is specified in the current style. If these shapes aren't enough,
the more primitive <tt>path</tt> methods allow you to assemble complex shapes yourself
using individual elements. This example draws a rectangle, with the top of the
rectangle replaced by a wavy line.
</p>
<pre id="exampleDrawPath" class="example">
1. public void drawPath(PDFPage page)
2. {
3. PDFStyle style = new PDFStyle();
4. style.setLineColor(Color.black);
5. style.setFillColor(ColorPattern.star(Color.red, Color.blue, 20));
6. page.setStyle(style);
7.
8. <b>page.pathMove(100, 100);</b> <i>// Always start with pathMove</i>
9. <b>page.pathLine(100, 200);</b>
10. <b>page.pathBezier(130,300, 160,100, 200, 200);</b>
11. <b>page.pathLine(200, 100);</b>
12. <b>page.pathClose();</b>
13. <b>page.pathPaint();</b>
14. } </pre><p class="caption">Example 12 - Drawing a complex shape with path operations</p>
<p>
The <tt>pathLine</tt>, <tt>pathBezier</tt> and <tt>pathArc</tt> methods are available
to build up your shape. The only things to remember when drawing a shape with the
<tt>path</tt> operators is to start with <tt>pathMove</tt> and end with
<tt>pathPaint</tt>.
</p>
<h2 id="Transforms">Graphics state: Transforming the page</h2>
<p>
There are a few additional methods in the <tt>PDFPage</tt> class which can be used to
alter the page itself. The <tt>setUnits</tt> method has already been mentioned, allowing
you to redefine which corner of the page is (0,0) and which units you want to measure the
page in. More interestingly, the <tt>rotate</tt> method can rotate the coordinates
of a PDF page around a specified point. Take a look at the watermark on each page of this
document for an example.
</p>
<p>
Other useful functions do with with the graphics state are <tt>save</tt> and
<tt>restore</tt>. These allow you to save the current state of the page
to a "stack" - it's good practice to save before doing a transformation and restore
afterwards rather than apply a reverse transformation. For example, here's how to draw some
text on the page at 45° without affecting all future operations as well.
</p>
<pre id="exampleSaveUndo" class="example">
1. public void drawRotatedText(PDFPage page, String text, float x, float y)
2. {
3. <b>page.save();</b>
4. page.rotate(x, y, 45);
6. page.drawText("Hello, World", x, y);
5. <b>page.restore();</b>
7. } </pre><p class="caption">Example 13 - the Rotate, Save and Restore methods</p>
<h2 id="GraphicsStyle">Graphics styles</h2>
<p>
Various aspects of the <tt>PDFStyle</tt> class can be used to alter the look of the
various graphics methods (although they also work on text, they're more likely to be used
with graphics elements).
</p>
<table width="100%">
<tr id="methodPDFStyle_setLineWidth">
<td class="imgexample" width="400">
<shape width="200" margin-top="10" height="20" border-color="black" border="1">
<shapepath>
<moveto x="10%" y="0"/><lineto x="90%" y="0"/>
</shapepath>
</shape>
<shape width="200" margin-top="5" height="20" border-color="black" border="2">
<shapepath>
<moveto x="10%" y="0"/><lineto x="90%" y="0"/>
</shapepath>
</shape>
<shape width="200" margin-top="5" height="20" border-color="black" border="4">
<shapepath>
<moveto x="10%" y="0"/><lineto x="90%" y="0"/>
</shapepath>
</shape>
<shape width="200" margin-top="5" height="20" border-color="black" border="8">
<shapepath>
<moveto x="10%" y="0"/><lineto x="90%" y="0"/>
</shapepath>
</shape>
</td>
<td class="imgexamplehead" width="400">
<p font-size="9">
The <tt>setLineWidth</tt> method sets the width of any lines that are drawn,
including outlined text and shapes. The width can be any positive number, and is
specified in points. Setting a line width of zero is allowed and instructs the
viewing device to create the <i>thinnest line possible on that device</i>. In
Acrobat Viewer, this is 1 pixel wide, regardless of the zoom level of the
document, while on a high resolution printer this may be nearly invisible. Because
of it's device dependent nature, this is not recommended by Adobe.
</p>
</td>
</tr>
<tr id="methodPDFStyle_setLineCap">
<td class="imgexample">
<div width="200" height="80">
<div position="absolute">
<shape width="200" height="80" border-color="red">
<shapepath>
<moveto x="30" y="5"/><lineto x="30" y="75"/>
<moveto x="170" y="5"/><lineto x="170" y="75"/>
</shapepath>
</shape>
</div>
<div position="absolute">
<shape width="200" height="80" border-color="black" border="10" line-cap="butt">
<shapepath>
<moveto x="30" y="20"/><lineto x="170" y="20"/>
</shapepath>
</shape>
<shape width="200" height="80" border-color="black" border="10" line-cap="round">
<shapepath>
<moveto x="30" y="40"/><lineto x="170" y="40"/>
</shapepath>
</shape>
<shape width="200" height="80" border-color="black" border="10" line-cap="square">
<shapepath>
<moveto x="30" y="60"/><lineto x="170" y="60"/>
</shapepath>
</shape>
</div>
</div>
</td>
<td class="imgexamplehead">
<p font-size="9">
The <tt>setLineCap</tt> method changes how the end of lines are drawn. The default
option is <i>Butt cap</i>, where the stroke is squared off at the endpoint of the
path and there is no projection beyond the end. Second is <i>Round cap</i>,
causing a semicircle with a diameter equal to the line width to be drawn at the
end of the line. Finally the <i>Square cap</i>, where the stroke continues beyond
the endpoint of the path for a distance equal to half the line width, and is then
squared off.
</p>
</td>
</tr>
<tr id="methodPDFStyle_setLineJoin">
<td class="imgexample">
<div width="200" height="90">
<shape width="50" height="90" position="absolute" x="20" border="10" border-color="black" line-join="miter">
<shapepath>
<moveto x="30" y="70"/><lineto x="10" y="20"/><lineto x="50" y="50"/>
</shapepath>
</shape>
<shape width="40" height="90" position="absolute" x="70" border="10" border-color="black" line-join="round">
<shapepath>
<moveto x="30" y="70"/><lineto x="10" y="20"/><lineto x="50" y="50"/>
</shapepath>
</shape>
<shape width="40" height="90" position="absolute" x="120" border="10" border-color="black" line-join="bevel">
<shapepath>
<moveto x="30" y="70"/><lineto x="10" y="20"/><lineto x="50" y="50"/>
</shapepath>
</shape>
</div>
</td>
<td class="imgexamplehead">
<p font-size="9">
The <tt>setLineJoin</tt> method changes how two line segments are joined. The
default is a <i>Miter join</i>, where the outer edges of the two strokes are
extended until they meet at an angle, as in a picture frame. For extremely sharp
angles a bevel join is used instead. Second is a <i>Round join</i>, where a circle
with a diameter equal to the line width is drawn around the point where the two
segments meet and is filled in, producing a rounded corner. Finally, the <i>Bevel
join</i>, where the two segments are finished with butt caps and the resulting
notch is filled with a triangle.
</p>
</td>
</tr>
<tr id="methodPDFStyle_setLineDash">
<td class="imgexample">
<div width="200" height="90" padding-top="10">
<shape width="200" height="20" border="2">
<shapepath>
<moveto x="10%" y="0%"/><lineto x="90%" y="0%"/>
</shapepath>
</shape>
<shape width="200" height="20" border="2" border-style="5,5,0">
<shapepath>
<moveto x="10%" y="0%"/><lineto x="90%" y="0%"/>
</shapepath>
</shape>
<shape width="200" height="20" border="2" border-style="15,5,0">
<shapepath>
<moveto x="10%" y="0%"/><lineto x="90%" y="0%"/>
</shapepath>
</shape>
<shape width="200" height="20" border="2" border-style="15,5,10">
<shapepath>
<moveto x="10%" y="0%"/><lineto x="90%" y="0%"/>
</shapepath>
</shape>
</div>
</td>
<td class="imgexamplehead">
<p font-size="9">
The <tt>setLineDash</tt> method allows you to change the line into a sequence of
<i>on</i> and <i>off</i> line segments. The default is a solid line, the result of
calling <tt>setLineDash(0,0,0)</tt>. The second example here is a sequence of 5
points on, 5 points off, from <tt>setLineDash(5,5,0)</tt>. The third example is 15
points on, 5 points off, from <tt>setLineDash(15,5,0)</tt>. The final example is
the same as number 3, but the <i>phase</i> of the pattern has been changed by
calling <tt>setLineDash(15,5,10)</tt>. The pattern of 15 on, 5 off, 15 on, 5 off
starts ten pixels in, and the result is 5 on, 5 off, 15 on, 5 off, 15 on and so
on.
</p>
</td>
</tr>
</table>
<!--<p class="caption">Table 4 - Graphics Styles</p>-->
<h1 id="Manipulating">Section 2. Importing and Editing existing documents</h1>
<p>
In version 1.1.12 we added the <code>PDFReader</code> class, which allows existing
PDF documents to be read, modified and written. This framework has been completely
overhauled for version 2.0, and is now much more stable and about twice as fast.
The <code>PDFReader</code> class, which is required to read an existing document,
is part of the <i>Extended Edition</i> of the library - you'll need to remember this
when deciding which version to purchase.
</p>
<p>
One of the most common uses for the Extended PDF library is filling a blank form with
data, possibly concatenating all the results together and then sending the document
either back to the browser or to some other <code>OutputStream</code>. A read through
the following section will be helpful to anyone planning to implement something like this.
</p>
<p>
So how do you import and edit a PDF? Let's take a fairly typical example first - the
concatenation of several documents into one.
</p>
<pre id="exampleConcatenate" class="example">
1. import java.io.*;
2. import org.faceless.pdf2.*;
3.
5. public class Concatenate
6. {
7. public static void main(String[] args) throws IOException
8. {
9. PDF out = new PDF();
10. for (int i=0;i<args.length;i++) {
11. FileInputStream in = new FileInputStream(args[i]);
12. <b>PDFReader reader = new PDFReader(in);</b>
13. in.close();
14. <b>PDF pdf = new PDF(reader);</b>
15.
16. <b>out.getPages().addAll(pdf.getPages());</b>
17. }
18. out.render(new FileOutputStream("Concatenated.pdf"));
19. }
20. } </pre><p class="caption">Example 14 - Concatenating several documents</p>
<p>
Significant lines here include line 12 and 14, where the next PDF is read in
from an <code>InputStream</code> (in this case a <code>FileInputStream</code>, but
they could be read in from a database, a URL, a <code>ByteArrayInputStream</code>
or similar - any <code>InputStream</code> will do).
</p>
<p>
The next interesting bit is line 16, where all the pages are <b>moved</b>, not copied,
from the PDF we just read in to our output PDF. This is done by manipulating the list
of pages returned by the <code>getPages</code> method in the <code>PDF</code> class.
This returns a standard <code>java.util.List</code>, which can be manipulated in any
of the usual ways.
</p>
<h2 page-break-after="avoid" id="MovingPages">The trouble with page moves</h2>
<p>
The ability to move pages from one PDF to another also doesn't come freely. Although
the library takes care of a lot of the "dirty work", the programmer must also be
aware of what he does when it comes to links within the document. Imagine a document
containing two pages, with page 1 containing a hyperlink to page 2. If page 2 is
deleted, a warning will be printed to <code>System.err</code> and the hyperlink
action removed. The same applies to bookmarks linking to that page (which are
<i>not</i> copied when a page is copied), and form fields, which may exist on more
that one page at a time and therefore <i>are not</i> transferred when moving pages (although
they can be moved separately). Here's a list of things to watch for when manipulating
a documents pages.
</p>
<ul>
<li>
A page can only ever be in one PDF at a time, and can only exist in a PDF once. If
you want to copy a page, rather than move it, you should clone it first, like so:
<pre class="example">
PDFPage copy = new PDFPage(original);
newpdf.getPages().add(copy);
</pre>
</li>
<li>
<p>
If you're cloning all the pages in the document, why not clone the entire document
instead? This is almost certainly going to be faster, and gets around several nasty
potential problems with form fields: Try something like this:
</p>
<pre id="exampleClone" class="example">
1. PDF template = new PDF(new PDFReader(new FileInputStream("Template.pdf")));
2. PDF out = new PDF();
3. for (int i=0;i<10;i++) {
4. PDF copy = new PDF(template);
5. out.getPages().addAll(copy); <i>// out now has 10 copies of "Template.pdf"</i>
6. } </pre><p class="caption">Example 15 - Cloning a document</p>
</li>
<li>
Manipulating documents containing Form Fields can cause confusion - so much so
that we've given it it's <a href="#CompletingForms">own section</a>.
</li>
</ul>
<h2 page-break-after="avoid" id="Stamping">Stamping documents</h2>
<p>
There are some other useful things you can do with a document that's been read in. First
and most obvious, you can write to it's pages in the same way as with a newly created
document. For instance, to add a message or watermark to every page:
</p>
<pre id="exampleStamp" class="example">
1. PDFStyle style = new PDFStyle();
2. style.setFont(new StandardFont(StandardFont.HELVETICA), 12);
3. style.setFillColor(Color.black);
4.
5. PDF pdf = new PDF(new PDFReader(inputstream));
6.
7. for (int i=0;i<pdf.getPages().size();i++) {
8. PDFPage page = pdf.getPage(i);
9. page.setStyle(style);
10. page.drawText("Received "+new Date(), 10, 10);
11. }
12.
13. pdf.render(outputstream); </pre><p class="caption">Example 16 - Stamping each page of a document</p>
<p>
Power users might like to try using translucent colors and the <code>rotate</code> method
to stamp text on top of the page. Another alternative would be to create and attach a new Stamp
<code>Annotation</code> for each page. All of these options are demonstrated in the
<code>Stamp.java</code> example included in the examples supplied with this library.
</p><p>
These methods work fine with Acrobat 5.0, but earlier versions don't support transparency
and so would result in text being obscured. One method we found quite effective is to write
the stamp <i>under</i> the current contents of the page, rather than over top. This is done
with the <code>seekStart</code> method, which moves the page "cursor" to the start of the pages
contents. This method isn't bullet-proof - some documents clear the background first, which
will overwrite the stamp - but it works in many cases. Here's the above example with two new
lines (9 and 12) added to draw the stamp under any current content on the page.
</p>
<pre id="exampleUnderStamp" class="example">
1 PDFStyle style = new PDFStyle();
2 style.setFont(new StandardFont(StandardFont.HELVETICA), 12);
3 style.setFillColor(Color.black);
4.
5. PDF pdf = new PDF(new PDFReader(inputstream));
6.
7. for (int i=0;i<pdf.getPages().size();i++) {
8. PDFPage page = pdf.getPage(i);
9. <b>page.seekStart();</b> <i>// Move to start of page stream</i>
10. page.setStyle(style);
11. page.drawText("Received "+new Date(), 10, 10);
12. <b>page.seekEnd();</b> <i>// Move back to the end.</i>
13. }
14.
15. pdf.render(outputstream); </pre><p class="caption">Example 17 - Stamping each page under the current content</p>
<h2 page-break-after="avoid" id="drawCanvas">Stamping Whole Pages - a Page is a Canvas</h2>
<p>
Another possibility is to use the contents of a page as an image or "Canvas",
to be painted onto another page. We visited canvases briefly in the <a href="#CustomPatterns">
Patterns</a> section, but essentially a Canvas is like it's equivalent in the art
world; a sheet of virtual paper with markings on it. A page is simply a canvas
with optional annotations on top.
</p><p>
This allows for some interesting ideas. Rather than cloning a page, you could
simply turn it into a canvas and "draw" it onto another page, as you would an
image. The effect is visually similar to cloning a page, although the concepts
are quite different. Which method you choose depends on what your needs are.
</p><p>
One the one hand, when converting to a PDFCanvas you will lose any form fields
and annotations on the page - only the fixed contents of the page will be taken.
On the other hand, by treating a page as an image and repeatedly drawing it over
and over, the image-page only needs to be saved in the PDF once. For documents that
contain one or two pages repeated over and over, this can produce much smaller
files. Here's an example of how you might do this - we write some information from
an abstract set of records onto a sequence of pages:
</p>
<pre id="exampleTemplate" class="example">
1. PDFStyle style = new PDFStyle();
2. style.setFont(new StandardFont(StandardFont.HELVETICA), 12);
3. style.setFillColor(Color.black);
4.
5. PDF templatepdf = new PDF(new PDFReader(inputstream));
6. <b>PDFCanvas template = new PDFCanvas(templatepdf.getPage(0));</b>
7.
8. PDF pdf = new PDF();
9. while (hasMoreRecords()) {
10. PDFPage page = pdf.newPage(PDF.PAGESIZE_A4);
11. <b>page.drawCanvas(template, 0, 0, page.getWidth(), page.getHeight());</b>
12. page.setStyle(style);
13. page.drawText(record.getName(), 100, 100);
14. page.drawText(record.getAddress(), 200, 100);
15. }
14.
15. pdf.render(outputstream); </pre><p class="caption">Example 18 - Using a page as a template canvas</p>
<p>
One thing to note here is that the canvas and text are both being drawn onto the page,
rather than form fields being filled out, which is obviously a lot easier. We can't
use a form in this case, simply because a canvas doesn't have annotations. Of course,
there's nothing to stop you going through the original form in <code>templatepdf</code>,
and finding out where the fields are positioned by checking their annotations, and writing
the text to the same position in the new PDF... but we'll leave that as an exercise for
the reader.
</p>
<h2 id="CompletingForms">Completing Forms</h2>
<p>
We'll cover forms in more detail <a href="#Forms">elsewhere</a>, but we want to add a little
bit here on batch completion of forms - the focus here is not so much on creating form fields
and how they work, but on various "Gotchas" that can occur when trying to complete large
numbers of forms in a batch.
</p>
<p>
First, some things you should know. Each PDF can have only one form (unlike HTML which can
have many forms). Each field has a name, which much be unique across the form (and
therefore, the document). Somewhat confusingly, a field may have more than one visible
appearance in the document - each represented by a special type of Annotation called a
"Widget". Although each may have a different style and be on a different page, they must
all have the same value. Finally, forms take up a lot of space in the document.
</p>
<p>
With that in mind, let's look at some typical situations and the things that can go wrong.
Lets say you have a template PDF with a form. This needs to be completed for each
customer and the results concatenated together into one large document. Here's a way to
do it that's clear, simple and <i>wrong</i>.
</p>
<pre id="exampleConcatenateForm" class="example">
1. PDF template = new PDF(new PDFReader(templatestream));
2. PDF out = new PDF();
3.
4. while ((record=nextRecord())!=null) {
5. PDF clone = new PDF(template);
6. Form form = clone.getForm();
6. ((FormText)form.getElement("Name")).setValue(record.getName());
7. ((FormText)form.getElement("Phone")).setValue(record.getPhone());
8.
9. out.getPages().addAll(clone.getPages());
10. out.getForm().getElements().putAll(form.getElements());
11. } </pre><p class="caption">Example 19 - The incorrect way to concatenate documents with forms</p>
<p>
The idea here is fairly simple. For each record we clone the template (line 5), complete
the form (line 6 and 7), then move all it's pages (on line 9) and all it's form elements
(on line 10) to the output PDF. The problem is that after the first record has been added,
the <code>out</code> PDF will already contain a FormElement called "Name". Trying to add
another one will cause an error.
</p>
<p>
There are two ways around this. The first method is to flatten the form. Flattening a form
permanently stamps all it's elements onto the page, preventing them from being altered,
but it does have the pleasing side effect of drastically reducing the resulting file size.
This would be done in the example above by adding the line <code>form.flatten()</code> at
line 8. We could also remove line 10 altogether, as once a form is flattened there are no
fields left to move.
</p>
<p>
This solution is the one we'd generally recommend. However, if you need the combined form
to be editable, your only option is to rename the form elements so that each one has a unique
name. The easiest way to do this is to call the <code>Form.renameAll</code> method - perhaps
adding at line 8 something like
<code>form.renameAll("", "_"+(recordnum++));</code>. This would add a unique suffix to
each element - "_1" for the first record, "_2" for the second and so on.
</p>
<h1 id="Interaction">Interaction: Actions, Hyperlinks and Annotations</h1>
<h2 id="Actions">Actions</h2>
<p>
The <code>PDFAction</code> class allows the user to interact with the document. Actions are
used in several places throughout a PDF.
</p>
<ul>
<li>Each bookmark uses an action to determine what happens when it's clicked on</li>
<li>
An action can optionally be run when a document is opened, closed, printed or saved,
by calling the <code>PDF.setAction</code> method
</li>
<li>
An action can optionally be run when a page is opened or closed, by calling the
<code>PDFPage.setAction</code> methods.
</li>
<li>
<code>AnnotationLink</code> annotations have an action associated with them, which
runs when they're clicked on.
</li>
<li>
A form element and it's Widgets can have actions associated with them, to do things
when a field receives focus, when a key is pressed, it's value changed, and so on.
</li>
</ul>
<p>
A number of different types of action are provided for in the <tt>PDFAction</tt> class.
The various <tt>goTo</tt> actions allow the user to navigate to a specific page in the
document, and different variations exist to bring the page up zoomed to fit, or to have a
specific rectangle visible. New in version 1.1 were the <tt>goToURL</tt> action (which is
used in the hyperlink examples below), the <tt>playSound</tt> action which should be
fairly obvious, and one other which isn't - the <tt>named</tt> action.
</p>
<p>
This last one will probably only work under Adobes own Acrobat viewer, but allows a
measure of interaction with the viewer itself. A named action corresponds to
selecting an action from the drop-down menus in Acrobat, and allow the user to
print the document, quit the browser, search for text and so on. This is poorly documented
in the PDF specification, but what information we have is available in the API
documentation for this method. If you're trying to recreate a specific action that you've
seen in Acrobat, what we suggest is create a document in Acrobat with that action, then
run it through the <code>Dump.java</code> example to see what it's called.
</p>
<p>
Six other action types are mostly used with forms - the <code>formSubmit</code>,
<code>formReset</code>, <code>formImportData</code>, <code>formJavaScript</code>,
<code>showWidget</code> and <code>hideWidget</code>. These are usually applied to a form
elements annotation via the <code>WidgetAnnotation.setAction</code> and
<code>FormElement.setAction</code> methods, and are covered separately in the section on forms.
</p>
<h2 id="Hyperlinks">Hyperlinks</h2>
<p>
A special subclass of annotation is the Hyperlink, represented by the
<code>AnnotationLink</code> class. Like all annotations, these sit <i>above</i> the page
content, rather than being a part of it.
</p>
<p>
An <code>AnnotationLink</code> annotation takes a <tt>PDFAction</tt>, which can be any of the
actions available with the library - a link to a URL or another part of the document, play
a sound, print the document and so on.
</p>
<p>
Positioning a link to match some text placed on the page means knowing where the
exactly text is. There are two ways to do this. The first, for those using the
<code>beginText</code> and <code>endText</code>, is to call the
<code>beginTextLink</code> and <code>endTextLink</code> methods in the
<code>PDFPage</code> class. The second is to get the coordinates of the
text or object you're trying to make a hyperlink, and use those to set the rectangle
of the Annotation by calling it's <code>setRectangle</code> method. The coordinates
are easily obtained by getting the rectangle of the <code>LayoutBox.Box</code> used
to position the text. For example:
</p>
<pre id="exampleLayoutBoxLink" class="example">
1. LayoutBox box = new LayoutBox(100);
2. box.addText("some text here");
3. LayoutBox.Text linktext = box.addText("hyperlink goes here");
4. box.addText("some more text here");
5. box.flush();
6.
7. page.drawLayoutBox(box, 200, 300);
8.
9. do {
10. AnnotationLink link = new AnnotationLink();
11. link.setRectangle(200+linktext.getLeft(), 300+linktext.getBottom(),
10. 200+linktext.getRight(), 300+linktext.getTop());
11. page.addAnnotation(link);
12. linktext = linktext.getNextTwin();
13. } while (linktext!=null); </pre><p class="caption">Example 20 - Creating Hyperlinks over a LayoutBox.Box</p>
<p>
Key things to note here are that we have to loop around the text boxes returned by
<code>getNextTwin</code>, because it's possible that the text we want to
make a hyperlink was split over two or more lines. Also we need to add the
coordinates of the <code>LayoutBox</code> to the hyperlink, as the coordinates
returned by <code>getLeft()</code> and friends are relative to the <code>LayoutBox</code>.
For creating hyperlinks over images and so on, it's a lot easier - just specify the
coordinates directly in the <code>AnnotationLink.setRectangle</code> method call.
</p>
<p>
The second method is to use the <tt>beginTextLink</tt> and <tt>endTextLink</tt> methods of
the <tt>PDFPage</tt> class to add hyperlinks in the middle of a line of text. Here's how:
</p>
<pre id="exampleTextLink" class="example">
1. public void showTextLink(PDFPage page)
2. {
3. <b>PDFAction action = PDFAction.goToURL(new URL("http://big.faceless.org"));</b>
4.
5. page.beginText(50,50, page.getWidth()-50, page.getHeight()-50);
6. page.drawText("Thank you for choosing ");
7. <b>page.beginTextLink(action, PDFStyle.LINKSTYLE);</b>
8. page.drawText("the Big Faceless PDF Library");
9. <b>page.endTextLink();</b>
10. page.endText(false);
11. } </pre><p class="caption">Example 21 - Creating Hyperlinks using beginTextLink/endTextLink</p>
<p>
The <tt>beginTextLink</tt> method takes two parameters, the first a <tt>PDFAction</tt>, as
described above, and the second a <tt>PDFStyle</tt>. The style is optional (it can be
left null for no effect), but is a convenient way of marking the hyperlinked region of
text. Here we use the predefined style <tt>PDFStyle.LINKSTYLE</tt> which underlines the
text in the same way as an HTML hyperlink (as we've done in this document), but a
user-defined style can be used instead for a different effect. This method handles the
case where a hyperlink wraps at the end of the line, or even at the end of the page.
</p>
<h2 id="OtherAnnotations">Other Annotations</h2>
<p>
A good number of annotations are defined in the PDF specification - the ability to attach
files and other useful features are all there. Many of these require the full version of
Adobe Acrobat, and aren't supported by this library at the moment.
</p>
<p>
Two types of annotation that we do support are the <i>note</i> and <i>rubber-stamp</i>
annotations. The <i>note</i> annotation is the electronic equivalent of adding a
Post-It® note to your document. This can be clicked on by the viewer to view it's
contents or dragged about the page to a different location.
</p>
<p>
Notes are represented by the <tt>AnnotationNote</tt> class, and stamps by the
<code>AnnotationStamp</code> class we've already mentioned above. Both of these can be
drawn in a number of different pre-defined styles, and custom Stamps can be created by
using a <code>PDFCanvas</code>, in the same way as a <a href="#CustomPatterns">custom pattern</a>.
This is useful for applying "Received on DD-MMM-YYYY" type stamps. Alternatively, advanced
users may pre-define and save custom patterns. How? Read on...
</p>
<h1 id="Forms">Forms</h1>
<p>
<div float="right" class="note" id="noteFormElements">
<table>
<tr><td>Text Box</td><td colspan="3"><input type="text" name="sampletext"/></td></tr>
<tr><td>
Choice Box
</td><td colspan="3">
<input type="select" name="samplechoice" value="Monday">
<option>Monday</option>
<option>Tuesday</option>
<option>Wednesday</option>
<option>Thursday</option>
<option>Friday</option>
</input>
</td></tr>
<tr><td>Check Boxes</td>
<td><input type="checkbox" name="samplecheck1"/></td>
<td><input type="checkbox" name="samplecheck2"/></td>
<td><input type="checkbox" name="samplecheck3"/></td>
</tr>
<tr><td>Radio Buttons</td>
<td><input type="radio" name="sampleradio" value="first"/></td>
<td><input type="radio" name="sampleradio" value="second"/></td>
<td><input type="radio" name="sampleradio" value="third"/></td>
</tr>
<tr><td>Button</td>
<td colspan="3"><input type="button" name="samplebutton" value="Submit" onClick="javascript:showform()"/></td>
</tr>
</table>
</div>
Users of the <i>Extended Edition</i> of the library can read and create PDF forms, also
called "AcroForms". Users who just want to complete a pre-existing form will probably find
this section useful, but may get more mileage from the <a href="#CompletingForms">Completing Forms</a>
section.
<br/><br/>
These are part of a PDF document, in the same way a
<code><form></code> tag in HTML creates a form on a web page. Like HTML forms, PDF
forms can contain text-boxes, radio buttons, checkboxes, drop-down lists and push buttons,
can reference JavaScript functions or submit the form to a website.
<br/><br/>
<i>
Forms are not the simplest area of a PDF document to understand, and if you're just
starting with forms this document is the wrong place to start. Forms can be created from
within Acrobat, and there are several guides with that product and on the net which
explain about form fields, JavaScript, form submission and so on.
</i>
</p>
<p>
Each PDF document has a single form (unlike HTML, where one page may have several forms),
and the elements of this form may be spread across several pages. The
<code>PDF.getForm()</code> method is used to return the documents form, and from there the
various methods in the <code>Form</code> class can be used to set and retrieve elements. It's
important to note that because each document can only have a single form, each field in the
form must have a distinct name.
</p>
<p>
Each form element is a subclass of <code>FormElement</code>, and has a value which can be
set or retrieved via the <code>setValue</code> and <code>getValue</code> methods. For many
applications of forms, where the values on an existing form are read or written to, this
is as much of the API that will be required.
</p>
<p>
For creating new forms, we need to get a little deeper. New elements can be created and
added to the form using the <code>Form.addElement</code> method - don't forget this last
step, or you'll be wondering why your fields aren't showing up!. All form elements can
have a style set with the <code>setStyle</code> method, although not every feature of a
style can be used in a form field.
</p>
<p>
Most form elements have a visual representation on the page - some, like radio buttons,
have several, whereas digital signatures (covered later) often have none. This
representation is a special class of <code>PDFAnnotation</code> called a
<code>WidgetAnnotation</code>. The list of annotations associated with an element are
returned by the <code>FormElement.getAnnotations</code> method.
</p>
<p>
Finally, one of the more interested aspects of form elements is the triggers or "Events"
which can occur. Just like HTML, it's possible to call a JavaScript function (or other
action) when the value of a field is changed, when the mouse enters a field or when a key
is pressed inside one. The <code>setAction</code> method can be called on the
elements' annotations or on the element itself (depending on the action you want to set),
to submit a form, run some JavaScript, jump to another page or any
other action you can think of. The example on this page calls a JavaScript function when
the submit button is clicked.
</p>
<p>
Let's start with a simple example. Reading and writing values to an existing form is very
easy, and probably for most Form users, this is as far as you'll need to go:
</p>
<pre id="exampleFormSimple" class="example">
1. PDF pdf = new PDF(new PDFReader(new FileInputStream("template.pdf")));
2. <b>Form form = pdf.getForm();</b>
3.
4. <b>FormText name = (FormText)form.getElement("name");</b>
5. System.out.println("The name field was set to "+name.getValue());
6.
7. <b>name.setValue("J. Quentin Public");</b> </pre><p class="caption">Example 22 - Setting a form field</p>
<p>
As you can see, you first call the <code>getForm()</code> method to get the documents AcroForm,
then the <code>getElement</code> method on that form to return a specific element (there are
other ways to do this - the <code>Form</code> class has methods that return a <code>Map</code>
of all the elements, for example). Once you've got the element, you can get or set the value
using the <code>getValue</code> and <code>setValue</code> methods as required. When the
document is eventually written out using the <code>render</code> method, the form is written
out with the last values that were set.
</p>
<p>
Creating your own form fields isn't that much harder. All the elements have a consistent
interface. Starting with the basics, here's how to add a text field to a new PDF.
</p>
<pre id="exampleFormCreation" class="example">
1. PDF pdf = new PDF();
2. PDFPage page = pdf.newPage(PDF.PAGESIZE_A4);
3. Form form = pdf.getForm();
4.
5. <b>FormText text = new FormText(page, 100, 100, 300, 130);</b>
6. <b>form.addElement("mytextfield", text);</b>
7.
8. pdf.render(outputstream); </pre><p class="caption">Creating a new Form element</p>
<p>
The text field is placed in the rectangle 100,100 - 300,130 on the specified page. The field
uses the default style for form elements - you can change this by calling the
<code>setTextStyle</code> and <code>setBackgroundStyle</code> methods on the <code>Form</code>
object, or you can customize the style for a single <code>WidgetAnnotation</code> by calling the
same methods - following on from the example above, something like <tt>text.getAnnotation(0).setTextStyle(style)</tt>
would do it.
</p>
<h2>Form Actions</h2>
<p>
It's possible to set actions on a form elements annotations, which can range from simply
submitting the form to calling complex JavaScript functions. The action can be any of the
actions created by the <code>PDFAction</code> class, some of which we've already seen. Here's a
quick summary.
</p>
<table id="tableActions" class="defns">
<tr><th>Action</th><th>Description</th></tr>
<tr><td>goTo</td><td>Jump to a specific page in the current document</td></tr>
<tr><td>goToURL</td><td>Jump to a specific hyperlink. As you would expect this requires a web browser to be installed.</td></tr>
<tr><td>playSound</td><td>Play an <a href="#Sound">audio sample</a></td></tr>
<tr><td>named</td><td>Run a named action</td></tr>
<tr><td>showElement</td><td>Display an annotation that was previously hidden</td></tr>
<tr><td>hideElement</td><td>Hide an annotation that was previously visible</td></tr>
<tr><td>formSubmit</td><td>Submit the form to a specified URL on a server</td></tr>
<tr><td>formReset</td><td>Rest the form to it's default values</td></tr>
<tr><td>formImportData</td><td>Import an FDF file into the form</td></tr>
<tr><td>formJavascript</td><td>Run a JavaScript action</td></tr>
</table>
<p class="caption">Table 5 - Form Actions</p>
<p>
The <code>goTo</code>, <code>playSound</code> and <code>named</code> actions are covered
elsewhere in the document, so we'll briefly cover the form-specific actions
<code>formSubmit</code> and <code>formJavascript</code> - <code>formReset</code> is fairly
obvious, and <code>formImportData</code> is for advanced use, and is better described in the
PDF specification.
</p>
<p>
First, <code>formSubmit</code>. As you might have guessed, this allows the form to be submitted
to a server. Like HTML forms, which can be submitted via GET or POST, there are several options
for how to submit the form, including HTTP POST, FDF (to submit the form in
Adobes own FDF format), and users of Acrobat 5.0 or later can submit the form as an XML document
or can actually submit the entire PDF document - wordy, but good for digitally signed
documents.
</p>
<p>
Next, the <code>formJavaScript</code> option, as demonstrated in the sample form above. Acrobat
comes with a version of JavaScript similar, but not identical to the JavaScript supplied with
most web browsers. Although the syntax is identical, the object model is very different -
browsers use the Document Object Model, or <i>DOM</i>, whereas Acrobats object model is
documented in it's own JavaScript guide in a file called <code>AcroJs.pdf</code> supplied with
Acrobat 5.0. It's also currently available for download from <a
href="http://www.planetpdf.com/codecuts/pdfs/tutorial/AcroJS.pdf">http://www.planetpdf.com/codecuts/pdfs/tutorial/AcroJS.pdf</a>.
JavaScript actions can define JavaScript code directly, or call a function in the "document
wide" JavaScript, which can be set via the <code>PDF.setJavaScript</code> method. This is
recommended for anything but the simplest JavaScript.
</p>
<p>
Finally, the <code>showWidget</code> and <code>hideWidget</code> actions. These can be used
to show or hide an existing widget annotation. This can be used to interesting
effects, as you can see by taking a look at the <code>example/FormVoodoo.java</code> example
supplied with the PDF library.
</p>
<h2 id="Events">Events</h2>
<p>
So when and how can you use these actions in a form? The most obvious time an action is
required is when using a <code>FormButton</code>, for example to submit a document. You can
call the <code>setAction</code> method on the buttons' widget to determine what to do when the the user
clicks on it. Some events apply to the field and some to the fields annotations (see the API
documentation for detail), and most of them will be familiar to most JavaScript programmers,
and include <code>onMouseOver</code>, <code>onFocus</code> and <code>onChange</code>. Example
uses could include verifying keyboard input in a text box by setting the <code>onKeyPress</code>
handler to ensure only digits are entered, or maybe the <code>onOtherChange</code> handler, which
is called when <i>other</i>
fields in the document are changed - useful for updating a read-only field with the total of
other fields, for example. In fact, we do just this in the
<code>examples/FormVoodoo.java</code> example which we mentioned earlier.
</p>
<h1 id="Signatures">Digital Signatures</h1>
<p>
Since version 1.1.13, PDF documents may be digitally signed by those running the
<i>Extended Edition</i> of the library. These are useful for two main purposed - one,
to identify the author of the document, and two, to provide notice if the document has
been altered after it was signed. This is done by calculating a checksum of the
document, and then encrypting that checksum with the "private key" of the author,
which can later be verified by a user with the full version of Adobe Acrobat or
Acrobat Approval™, although <i>not</i> the free Acrobat Reader, by comparing it
with the corresponding public key.
</p>
<p>
<i>Note: Applying Digital Signatures to a document requires some basic knowledge of
public/private key cryptography, which is a weighty topic. We provide a brief
description here, but some knowledge of public key cryptography is assumed.</i>
</p>
<p>
Digital Signatures are implemented in Acrobat via a plug-in or "handler". Over the years
the available handlers have changed slightly - Acrobat 4.0 came with a fairly limited
self-sign handler, and VeriSign produced a plug-in which could be used to certify PDF's
signed by their keys. Acrobat 6.0 was the first to be delivered with an out-of-the-box
solution for signing and verifying any PKCS#7 signature. The PDF library can sign and
verify Digital Signatures created with the old VeriSign handler, the original self-sign
and the new public-key Acrobat handlers, and the plugin used with the nCipher DSE-200
Timestamping engine. As the <code>SignatureHandler</code> class can be extended, other
handlers can be developed by the user if required.
</p>
<p>
So, how do you sign a document? As this is a userguide rather than a reference, we'll
step through how to do it without going into too much detail. See the API class
documentation for the <code>FormSignature</code> class for more depth.
</p>
<h2 id="SelfSignSignatures">Signing documents with the Adobe "Self-Sign" Handler</h2>
<p>
First, we'll cover the Adobe Self-Sign handler, which is supplied with every version of
Adobe Acrobat. This handler requires a self-signed key, which you can generate using the
<code>keytool</code> application that comes with Java. To generate a key, run the
following command:
</p>
<pre font-size="smaller">
keytool -genkey -keyalg RSA -sigalg MD5withRSA -keystore testkeystore -alias mykey</pre>
<p>
This will ask a number of questions and will eventually save the key to the file
"testkeystore". If you're going to try this, it's important to enter a two-letter
country code (rather than leaving it set to "Unknown"), otherwise Acrobat will be
unable to verify the signature.
</p>
<p>
Once you have the private key and it's accompanying certificates stored in the
keystore, the next trick is to sign the document. One method is just to use the
<code>Sign.java</code> example, supplied in the examples directory. If you want to
write your own code however, there's not much to it.
</p>
<pre id="exampleSig1" class="example">
1. <i>import java.security.KeyStore;</i>
2.
3. PDF pdf = makeMyPDF(); <i>// Create your PDF document somehow</i>
4.
5. KeyStore keystore = KeyStore.getInstance("JKS");
6. keystore.load(new FileInputStream("testkeystore"), storepassword);
7.
8. <b>FormSignature sig;</b>
9. <b>sig = new FormSignature(keystore, "mykey", secret, FormSignature.HANDLER_SELFSIGN);</b>
10.
11. <b>pdf.getForm().addElement("Test Signature", sig);</b>
12.
13. pdf.render(new FileOutputStream("signed.pdf"));</pre>
<p class="caption">Example 23 - Signing a document using the Self-Sign handler</p>
<p>
First, we create and load the KeyStore on lines 5 and 6 - <code>storepassword</code>
is a <code>char[]</code> array containing the password to decrypt the keystore. Then
we actually create the signature on line 9, by specifying the keystore, the key alias
("mykey"), the password for that key (also a <code>char[]</code>), and the type of
handler we want to verify this signature. Finally, on line 11 we add that signature to
the PDF documents' form.
</p>
<h2 id="VeriSignSignatures">Signing documents with the VeriSign Handler</h2>
<p>
To use VeriSign signatures you'll need the VeriSign "Document Signer" handler, freely
available for download from <a
href="http://www.verisign.com/products/acrobat">http://www.verisign.com/products/acrobat/</a>.
The signing procedure is the same except you change <code>HANDLER_SELFSIGN</code> to
<code>HANDLER_VERISIGN</code>. The difference comes in how you acquire the key, as
(unlike the Self-Sign handler) the key must be certified by VeriSign. These steps will
almost certainly apply to signing documents for verification with the Acrobat 6.0
handler as well - most of the work here is in getting the key.
</p>
<p>
Luckily you can get one for free by visiting <a
href="http://www.verisign.com/client/enrollment">http://www.verisign.com/client/enrollment</a>.
Just follow the "trial certificate" instructions and you'll be issue with a
private key and signed certificate by VeriSign which is good for 60 days, and is
installed into your browser. Getting it out of your browser into a form we can
use from Java is the next trick. For Internet Explorer:
</p>
<ul>
<li>Go to the "Tools" menu, select "Internet Options"</li>
<li>Select "certificates" (figure 1)</li>
<li>Select the certificate you want to export and click "Export"</li>
<li>Select "Yes", as you do want to export the private key</li>
<li>Include the entire certification path (figure 2)</li>
<li>The file is saved as a PKCS#12 keystore</li>
</ul>
<p>
For Netscape, go to the "Communicator" menu, select Tools -> Security Info".
Then select the certificate off the list and choose "Export".
</p>
<table width="100%">
<tr>
<td valign="middle" align="center">
<img src="resources/certshot1.png" dpi="150"/>
<p class="caption">Figure 5a</p>
</td><td valign="middle" align="center">
<img src="resources/certshot2.png" border="1px solid red" dpi="150"/>
<p class="caption">Figure 5b</p>
</td>
</tr>
</table>
<p>
To acquire a permanent key rather than a temporary one, you need to purchase one
from a CA like VeriSign (other CA's can be used, although it's unlikely that VeriSigns
plugin for Acrobat 5 will verify these out of the box. Acrobat 6 has a general PKI
plugin which should theoretically work with any CA in the Windows trusted CA list, although
what happens on non-windows boxes is anyones guess).
</p><p>
VeriSign sell a bewildering number of digital
products, but in order to sign documents we recommend the "Code Signing" key available
at <a href="http://www.verisign.com/products/signing/code">http://www.verisign.com/products/signing/code</a>.
They sell digital IDs specifically for signing JAR files, which is the one you want.
The process for this is a little different. You need to follow exactly the same process
as you would do to acquire a key for signing JARs, which is to say the following steps:
</p>
<ol>
<li>
Use the <code>keytool</code> program to generate an RSA/MD5 key, in exactly the same way as described
above for the <a href="#SelfSignSignatures">Self Sign</a> signatures.
</li>
<li>
Run <code>keytool -certreq -alias mykey</code> to generate a certificate signing request for
your new key. This will output a block of Base64 encoded data, which you need to cut and paste
into the appropriate section on VeriSigns website when prompted.
</li>
<li>
Once you're approved, the CA will send you a certificate reply chain. You need to copy this
chain into your keystore by running <code>keytool -import</code>, e.g.
<tt>keytool -import -alias mykey -file verisign.cer</tt>. The import must use the same alias
as the original key - here we're using "mykey".
</li>
</ol>
<p>
So now you have your private key and accompanying certificates in a Java keystore. If you
created a test certificate via IE or Netscape, the keystore is a PKCS#12 keystore,
an industry standard format which works out of the box in Java 1.4, but with earlier versions will
require the installation of an appropriate Java Cryptography Extension, or JCE. The
homepage for the JCE range is at <a href="http://java.sun.com/products/jce">http://java.sun.com/products/jce</a>,
which includes a list of providers. We developed with, and recommend the free JCE provided by
"The Legion of the Bouncy Castle" (<a href="http://www.bouncycastle.org">http://www.bouncycastle.org</a>).
Just download the package, add the JAR to your classpath and finally register the provider by adding a new
line to the <code><i>JAVA_HOME</i>/jre/lib/security/java.security</code> file as follows:
</p>
<pre>
security.provider.2=org.bouncycastle.jce.provider.BouncyCastleProvider</pre>
<p>
Once that's done, you can verify things are working by loading the PKCS#12 keystore
with the "keytool" program - use a command similar to the following to list the key
details and find out the alias of your private key:
</p>
<pre>
keytool -list -v -keystore mystore.pfx -storetype pkcs12 -storepass secret</pre>
<p>
Our alias (sometimes called "friendly name") was a decidedly unfriendly string of
about 30 hex digits. No matter - modify the code example above to use
this alias instead of "mykey", and change the "JKS" to a "pkcs12". You should now be
able to sign a PDF document using this key - something you can confirm by loading it
into a copy of Adobe Acrobat with the VeriSign handler installed, going to the
"Window" menu, selecting "Show Signatures" and verifying the signature.
</p>
<p>
Annotations can be added to digital signatures to give them a visible appearance on the page.
For more detail on this see the API, but the short version is that you can add a "standard"
appearance just by adding a regular annotation, like this (taken from the example
above, with line 10 inserted):
</p>
<pre id="exampleSignatureAnnotation" class="example">
8. FormSignature sig;
9. sig = new FormSignature(keystore, "mykey", secret, FormSignature.HANDLER_SELFSIGN);
10. <b>sig.addAnnotation(pdf.getPage(0), 100, 100, 200, 200);</b>
11. pdf.getForm().addElement("Test Signature", sig);
12.
13. pdf.render(new FileOutputStream("signed.pdf"));</pre>
<p class="caption">Example 24 - Adding an Annotation to a signature</p>
<p>
If you want to add a custom appearance, e.g. a photo or linedraw signature, you can define
one on a canvas and pass it in as a custom appearance. You'd do this by inserting a new
line between 9 and 10 in the example above that looked like this:
</p>
<pre class="example">
((PKCS7SignatureHandler)sig.getSignatureHandler()).setCustomAppearance(canvas, 0,0,0,0)</pre>
<p>
See the JavaDoc API for more detail on this.
</p>
<h2 id="SignatureVerifying">Verifying Signed Documents</h2>
<p>
As well as signing new documents, previously signed documents can be verified by
comparing their signing signature to a list of "trusted" certificates. For example,
verifying a document created by the VeriSign plugin is easy:
</p>
<pre id="exampleSig2" class="example">
1. <i>import java.security.KeyStore;</i>
2. <i>import java.security.cert.Certificate;</i>
3.
4. PDF pdf = new PDF(new PDFReader(input)); <i>// Load the PDF</i>
5.
6. KeyStore trusted = FormSignature.loadDefaultKeyStore(); <i>// Trusted Certificates</i>
7.
8. Map form = pdf.getForm().getElements();
9. for (Iterator i = form.keySet().iterator();i.hasNext();) {
10. String key = (String)i.next();
11. FormElement value = (FormElement)form.get(key);
12. if (value instanceof FormSignature)
13. {
14. // Verify the signature integrity
15. boolean integrity = ((FormSignature)value).verify();
16.
17. // Verify the signature covers the whole document
18. int pdfrevision = pdf.getNumberOfRevisions();
18. int sigrevision = ((FormSignature)value).getNumberOfRevisionsCovered();
19. boolean allcovered = (pdfrevision==sigrevision);
20.
21. // Find the first unverifiable certificate. Null means they're all OK.
22. Certificate badcert = ((FormSignature)value).verifyCertificates(keystore);
23. }
24. } </pre>
<p class="caption">Example 25 - Verifying a signature</p>
<p>
This example excerpt shows how to cycle through a documents digital signatures and
verify them:
</p>
<ul>
<li>
First checking the document <i>integrity</i>, which confirms the section of the document that
the signature covers hasn't been altered since it was signed.
</li>
<li>
Second checking the signature <i>scope</i>, to confirm that the digital signature covers the
entire file - that nothing has been appended to the file after signing.
</li>
<li>
Finally, checking the certificate <i>authenticity</i> by ensuring that the certificate chain
has been signed by a trusted certificate. Here we've loaded our trusted certificates on line
6, using a method which loads the same keystore that's used to verify signed JAR files.
</li>
</ul>
<p>
This keystore contains the VeriSign Root certificates, so we can easily verify VeriSign-signed
documents this way. But what about Adobe's Self-Sign handler? This handler doesn't have the
concept of a "trusted root certificate", and all it's keys are self-signed, so verifying
against a standard keystore is impossible - the above example would always return a certificate
on line 18. However, Adobe Acrobat 4.0 can export the public key that was used to sign a document,
which we can load as the "trusted" keystore. To export the public key from the Acrobat
"Self-Sign" handler, open Acrobat and go to the "Self-Sign" menu. From there, select "User
Settings", click the "Personal Address Book" tab and select "Export Key File". The file is
exported as an "Adobe Key File", or <code>.AKF</code> file - another proprietary keystore format
- which can be loaded using the <code>FormSignature.loadAKFKeyStore</code> method, which would
replace line 6 above. Users of Acrobat 5.0 can export their key as the industry standard
PKCS#12 keystore format, or as an <code>.FDF</code> file which can be loaded using the
<code>FormSignature.loadFDFKeyStore</code> method.
</p>
<h2 id="SignatureProvisos">Things to be aware of with Digital Signatures</h2>
<ul>
<li>
Signing a file causes all future changes to it - including the addition of new signatures -
to be appended to the file as a new "revision". When verifying a signature it's important to
confirm that the signature covers the whole file. Remember that only the latest signature will
cover the whole file, as every new signature adds a new revision. See the
<code>PDFReader</code> API documentation for more about PDF revisions.
</li>
<li>
The Adobe "Self-Sign" handler required each certificate to be personally verified,
as there is no concept of signing or root certificates - something to be think about
if you're thinking of using this handler for wide-scale deployment.
</li>
<li>
Although PDF documents may potentially have more than one digital signature, we
currently do not support signing with more than one.
</li>
<li>
The <code>Sign.java</code> and <code>Dump.java</code> examples supplied with the
library provide working code examples of signing and verifying signatures respectively.
</li>
<li>
The concept of "trust" is a complicated one with PKI. Although we've blindly decided
to trust the keystore supplied with Java and the certificates it contains, you
should make this decision yourself before simply loading the default keystore and
verifying using the <code>verifyCertificates</code> method (the list of certificates
can be extracted from the FormSignature object for manual verification). Remember
when it comes to cryptography it's not whether you're paranoid, but whether you're
paranoid enough.
</li>
<li>
Acrobat Reader prior to version 5.1 can not verify signatures at all - the full version
of Acrobat or Acrobat Approval was required.
</li>
</ul>
<h1 id="SpecialFeatures">Special Features</h1>
<p>
There are a number of features in the library that we haven't covered in the previous
sections. There's no way to classify most of these so we'll just list them all.
</p>
<h2 id="Sound">Sound</h2>
<p>
One of the less useful additions to the PDF format was the ability to play sounds. This
feature has patchy support amongst viewers, even Adobes own Acrobat viewers. Still, in
the best tradition of "feature creep" we thought we'd add it anyway. The
<tt>PDFSound</tt> class in the library handles all the formats listed as acceptable by
the PDF specification - Microsoft .WAV, Sun .AU and Macintosh .AIFF audio files (no
MP3s, sorry). However, we've found only the .WAV format works on the Windows Acrobat
viewers (and even that with some problems), and we can't get a peep out of our Linux
machine. Still, for the curious, click <a
href="pdf:playsound(resources/test.wav)">here</a> to hear this marvelous feature in
action (bonus points if you can name the tune).
</p>
<h2 id="Bookmarks">Bookmarks</h2>
<p>
The bookmarks (also called "outlines") feature of PDF documents is probably one of the
reasons they're so popular - allowing a true "table of contents" in larger documents.
The libraries support for bookmarks is based around the <tt>PDFBookmark</tt> and the
familiar <tt>java.util.List</tt> classes, allowing easy manipulation of complex chains
of bookmarks and simple creation of bookmark trees.
</p>
<h2 id="Encryption">Encryption and Access Levels</h2>
<p>
Documents can be encrypted to prevent unauthorized access, either by limiting what the
user can do with a document (i.e. they're not allowed to print it) or by adding a password.
The library supports both the 40-bit RC4 encryption used in Acrobat 3 and later, the 128-bit
RC4 encryption added in Acrobat 5 and the 128-bit AES encryption added in Acrobat 7.
This is best demonstrated by a couple of simple examples. First, here's how to encrypt a
PDF with 40-bit encryption so that it can be opened as normal in all versions of Acrobat,
but cannot be printed.
</p>
<pre id="example40BitEncryption" class="example">
1. PDF pdf = new PDF();
2. ... create contents of PDF here ...
3.
4. StandardEncryptionHandler enc = new StandardEncryptionHandler();
5. enc.setAcrobat3Level(false, true, true, true);
6. pdf.setEncryptionHandler(enc); </pre>
<p class="caption">Example 26a - Turning of Printing with 40-bit encryption</p>
<p>
Here's how to do the same thing, but using 128-bit encryption so the document can only be
opened in Acrobat 5 or later.
</p>
<pre id="example128BitEncryption" class="example">
1. PDF pdf = new PDF();
2. ... create contents of PDF here ...
3.
4. StandardEncryptionHandler enc = new StandardEncryptionHandler();
5. <b>enc.setAcrobat5Level(enc.PRINT_NONE, enc.EXTRACT_ALL, enc.CHANGE_ALL);</b>
6. pdf.setEncryptionHandler(enc); </pre>
<p class="caption">Example 26b - Turning of Printing with 128-bit encryption</p>
<p>
And here's how to encrypt with 40-bit again, but to require a password to open the document.
</p>
<pre id="examplePassword" class="example">
1. PDF pdf = new PDF();
2. ... create contents of PDF here ...
3.
4. StandardEncryptionHandler enc = new StandardEncryptionHandler();
5. enc.setUserPassword("secret");
6. pdf.setEncryptionHandler(enc); </pre>
<p class="caption">Example 26c - Setting encryption and a password</p>
<h2 id="CreatingCustomCanvases">Creating your own predefined canvases</h2>
<p>
For advanced users who know about PDF internals, it's possible to create your own
pre-defined canvases as <code>ResourceBundles</code>, which can be loaded in from a <code>properties</code>.
file. These can be used as stamps, as logos for signature handlers, or just
as an easier way to define complex canvases. The <code>AnnotationStamp</code>, <code>PDFCanvas</code>
and <code>PDFPattern</code> can all take the name of java resource bundle as an parameter.
</p><p>
Each <code>ResourceBundle</code> must have at least a <code>width</code> and <code>height</code>
attribute to size the canvas, and an <code>action</code> attribute which contains a sequence of
PDF stream operations. If the canvas needs to reference any resources, these may also be stored
as <i>direct objects only</i> by giving them an attribute name of <code>resource.X.Y</code>, where
<code>X</code> is the type of resource (Font, Pattern etc). and <code>Y</code> is the resource
name.
</p><p>
Confused yet? Remember, this is for advanced users, and although a useful time-saving device is not
necessary. What we'd recommend to get started is to extract some of the predefined canvases from
the <code>bfopdf.jar</code> file (they're all in the <tt>org.faceless.pdf2.resources.canvases</tt>
and <tt>org.faceless.pdf2.resources.patterns</tt> packages) and take a look. To get you started,
here's a couple of quick examples - the first showing how to create a pattern of alternating up and
down triangles, and the second showing how to create a stamp that simply says "Hello".
</p>
<pre id="exampleCustomCanvas" class="example">
# alternating up/down triangle pattern
#
width = 20
height = 20
action = 0 2 m 8 2 l 0 18 l f 10 4 m 18 20 l 2 20 l f 12 2 m 20 2 l 20 18 l f </pre>
<pre class="example">
# "Hello" stamp - draw a rectangle and write "Hello" in black 24pt Helvetica
#
name = Hello
width = 80
height = 40
resource.Font.F0 = <</Type /Font /Subtype /Type1 /BaseFont /Helvetica>>
action = 0 G 0 0 80 40 re S 0 g 1 0 0 1 10 30 Tm /F0 24 Tf (Hello) Tj </pre>
<p class="caption">Example 27 - Resource files for a custom Pattern and Stamp</p>
<p>
To the first one, you could save the file as, say, "yourcompany/Triangle.properties", then
create a new pattern by calling <code>new PDFPattern("yourcompany.Triangle", 0, 0, 20, 20,
Color.red, null)</code>. Note we need to specify the colors, as they're not set in the
pattern itself. The second one is a stamp, so you would save it as something like
"yourcompany/HelloStamp.properties", then create a stamp by calling <tt>new
AnnotationStamp("yourcompany.Hello");</tt>.
</p>
<p>
(Where this really comes into it's own is that with a bit of effort, you can create stamps in
Illustrator and the like, distill them as uncompressed PDFs, then extract the PDF stream and
save it out. This isn't as simple as it sounds, and you may wind up having to prefix the
extracted stream with some page coordinate transformations, but it can be done - it's just
not easy. Remember, this is for advanced users!)
</p>
<h2 id="BarCodes">Bar Codes</h2>
<p>
The <tt>drawBarCode</tt> method of the <tt>PDFPage</tt> class allows a bar code to be added
at a specific position on the page, in one of several encoding systems. The text of the
code can optionally be written underneath (as we've done here) and a checksum can be
added if the algorithm supports it.
</p>
<table class="defns">
<tr>
<td>
<barcode codetype="code39" value="CODE 39" showtext="true"/>
</td>
<td>
The Code 39 barcode is a simple system which can represent the digits, 26 upper-case
letters, the space and a few punctuation characters. We also support Extended Code
39, which supports more characters at the expense of even longer codes.
</td>
</tr>
<tr>
<td>
<barcode codetype="code25" value="20010908" showtext="true"/>
</td>
<td>
The Interleaved code 2 of 5 barcode is a simple system which can represent only the
ten digits, although it's fairly compact.
</td>
</tr>
<tr>
<td>
<barcode codetype="code128" value="Code 128" showtext="true"/>
</td>
<td>
The Code 128 barcode is a newer barcode which can represent almost all the US-ASCII
range of characters. It's also fairly compact. The algorithm chooses the appropriate
CODEB or CODEC variant depending on the data to be encoded, although this can be
overridden (see the BarCode class API documentation). For EAN128 codes, the
newline character (<code>'\n'</code>) can be used to embed an FCN1 control character
into the code.
</td>
</tr>
<tr>
<td>
<barcode codetype="ean13" bar-width="0.75" value="001234567890" height="0.5in"/>
</td>
<td>
The EAN-13 barcode is extremely common, and is generally used for product
labeling (it's the barcode on all your groceries and books). It must contain 13
digits, the last of which is a checkdigit.
</td>
</tr>
<tr>
<td>
<barcode codetype="upca" bar-width="0.75" value="01234567890" height="0.5in"/>
</td>
<td>
The UPC-A barcode is the US-only subset of EAN-13. Although all scanning equipment
in the US should be updated to recognize EAN-13 codes by 2004, in the meantime the
traditional UPC-A codes can also be printed.
</td>
</tr>
<tr>
<td>
<barcode codetype="codabar" value="A12345B" showtext="true"/>
</td>
<td>
The CodaBar barcode can represent the digits as well as the characters + - / $ :
and the decimal point (.). Special "start/stop digits" must be used to start and
stop the barcode - these are one of A, B, C or D.
</td>
</tr>
<tr>
<td>
<barcode codetype="postnet" value="90210" showtext="false"/>
</td>
<td>
The PostNet barcode is used by the US Postal Service to encode ZIP codes.
It uses digits only.
</td>
</tr>
<tr>
<td>
<barcode codetype="rm4scc" value="W1W5BB9Z" showtext="false"/>
</td>
<td>
The Royal Mail 4-state Customer Code is used by the Royal Mail in the UK
to encode PostCodes. It can represent digits and the upper case letters
A to Z.
</td>
</tr>
<tr>
<td>
<barcode codetype="pdf417" value="142 Charing Cross Road, London, WC2H0LB" width="80" height="25"/>
</td>
<td>
PDF417 is a "stacked" 2D barcode - probably the most common one. It's
used for a wide variety of purposes (for instance, paper archives of electronic
invoices in Spain must use PDF417). It's implemented by the
<code>PDF417BarCode</code> class.
</td>
</tr>
<tr>
<td>
<barcode codetype="qrcode" value="http://big.faceless.org" width="60"/>
</td>
<td>
QR-Code is a 2D barcode, invented and commonly used in Japan but making headway
elsewhere too, due to it's ability to store Kanji and it's incredible density -
the largest version can store over 6000 digits. It's implemented by the <code>QRCode</code>
class
</td>
</tr>
<tr>
<td>
<barcode codetype="maxicode" value="142 Charing Cross Road, London, WC2H0LB"/>
</td>
<td>
"MaxiCode" is a 2D barcode invented by UPS to code destinations on it's packages,
and is now in the public domain. It can encode up to 93 alphanumeric or 137 numeric
characters, and is implemented by the <code>MaxiCode</code> class
</td>
</tr>
</table>
<p class="caption">Table 7 - Bar Codes</p>
<h2 id="LayoutMeta">Document Layout and Meta-Information</h2>
<p>
The library can add meta-information about the document to the PDF with the
<tt>setInfo</tt> method in the <tt>PDF</tt> class, allowing you to set the author, title,
subject and so on. This can be viewed in Acrobat by going to the "Document Information" or
"Document Properties" option under the File menu.
</p>
<p>
You can also specify various options in the document, instructing the PDF viewer how to
display it (for instance, this document opens in Acrobat with the bookmarks pane already
open). The <tt>setLayout</tt> and <tt>setViewerPreferences</tt> methods in
the <tt>PDF</tt> class control various settings to do with what to do with the document
when it opens.
</p>
<h2 id="XML">XML Metadata (Adobe XMP™ support)</h2>
<p>
PDF documents supporting the PDF 1.4 specification can include XML meta-information
on almost any object in the document - pages, fonts, images or the document itself.
This XML is formatted using the Resource Description Framework (RDF), and the best
place to start with all this is <a
href="http://www.adobe.com/products/xmp">http://www.adobe.com/products/xmp</a>,
because a discussion of this is well beyond the scope of this document.
</p>
<p>
This potentially useful extension to the PDF format is supported by the library via
the <code>setMetaData</code> and <code>getMetaData</code> methods which are part of
several classes in the library. The XML data can be added or extracted from these
objects as a String, which can then be passed to an XML API like SAX or DOM, and
from there to an RDF-specific framework like Jena, available from <a
href="http://www.hpl.hp.com/semweb/arp.html">http://www.hpl.hp.com/semweb/arp.html</a>
</p>
<h2 id="OutputProfiles">Preflighting and Output Profiles - controlling how the document is written</h2>
<p>
PDF is quite a large specification with several useful subsets. An obvious example of a subset
is "PDFs that can be read by Acrobat 4" (which would rule out anything encrypted with 128-bit
encryption), and there are many other possibilities. One of the more interesting subsets is
"PDF/X", an ISO standard subset of PDF specially designed for use in the prepress industry.
The PDF library supports two of the most common variations of PDF/X, known as PDF/X-1a and
PDF/X-3.
</p>
<p>
Ensuring a PDF meets the requirements of a particular feature set is done with the
<code>OutputProfile</code> class. A PDF can have an Output Profile assigned to it with the
<code>PDF.setOutputProfile</code> method - prior to 2.6.1 this had to be done when it was
created, but with the arrival of the Viewer Extensions it's possible to parse an existing
PDF, determine it's feature set to ensure it matches the specified profile and (if possible)
adjust it to match. This process is generally known as <i>preflighting</i>.
</p><p>
Applying an output profile to a PDF that doesn't match, or trying to use a feature that is
disallowed in a PDFs output profile, will cause an <code>IllegalStateException</code> to be
thrown with information on what the restriction is. For instance, this will cause an
exception on line 6, because 128-bit encryption is not allowed in the Acrobat 4 profile:
</p>
<pre id="exampleOutputProfile" class="example">
1. PDF pdf = new PDF();
2. <b>pdf.setOutputProfile(OutputProfile.Acrobat4Compatible);</b>
3.
4. StandardEncryptionHandler enc = new StandardEncryptionHandler();
5. <b>enc.setAcrobat5Level(enc.PRINT_NONE, enc.EXTRACT_ALL, enc.CHANGE_ALL);</b>
6. pdf.setEncryptionHandler(enc); </pre>
<p class="caption">Example 28 - Using an OutputProfile to control the type of PDF written</p>
<p>
It's <i>sometimes</i> possible to load an existing PDF and adjust it to match an Output Profile.
Why only sometimes? As an example, PDF/X-1a:2001 doesn't allow
device-dependent RGB colors to be used in the PDF. Many PDFs do use RGB however - creating a
PDF with this library and using a <code>java.awt.Color</code> for text will create such a
PDF. The library doesn't convert RGB to CMYK, and so attempting to apply a PDF/X profile to
this PDF would throw an Exception on the <code>setOutputProfile()</code> method.
</p><p>
The <code>OutputProfile</code> API documentation has a lot more information on this, and
the <code>Preflight.java</code> example shows how to pre-flight an existing document against
the PDF/X-1a:2001 standard.
</p>
<pbr/>
<h1>The PDF Viewer Extensions</h1>
<h2 id="ParserIntro">About the Extension</h2>
<p>
The PDF Viewer extensions are a collection of classes that allow PDF documents to be
<i>parsed</i> - ie. the contents of the PDF are read, understood and converted to some other
form. Currently available conversions are <i>rasterization</i> - the conversion of the
PDF to a bitmap for viewing on the screen, printing or saving as an image,
and <i>plain text</i>, which allows the text and images of the PDF to be extracted.
More specifically, features include:
<ul>
<li>Conversion of PDF to multi-page TIFF (Black and White, GrayScale, RGB or CMYK)</li>
<li>
Conversion of PDF page to a <code>java.awt.image.BufferedImage</code>, for other image
formats such as PNG or JPEG.
</li>
<li>
Printing PDFs using the standard Java <code>Printable</code> and <code>Pageable</code>
interfaces.
</li>
<li>Extraction of text from a PDF</li>
<li>Indexing of text in a PDF using the Apache Lucene API</li>
<li>
Extraction of bitmap images from a PDF as <code>java.awt.image.BufferedImage</code> objects
</li>
<li>Embed PDF viewer in your own application using a <code>JPanel</code></li>
<li>Use the supplied PDF viewer sample application as a standalone viewer</li>
</ul>
</p>
<h2>Installation and getting started</h2>
<p>
No additional installation is required to use these classes, as they are included in the
<code>bfopdf.jar</code> package - this includes the <code>org.faceless.pdf2.viewer</code>
package containing the Swing components for an interactive PDF viewer application.
The exception to this is indexing the PDF using Apache Lucene - you will need the Lucene
jars in your classpath.
</p><p>
Unlike the rest of the library the rasterization code in the <code>PDFParser</code> makes
heavy use of the <code>java.awt</code> package, so UNIX users running Java 1.3 or earlier
will require X11 running (this does not apply for text extraction). Mac users will find that
the rasterization process tends to crash Java 1.4 on OS X - we recommend Mac users run at
least Java 1.5. Finally the <code>PDFViewer</code> class (the sample Swing application we
supply to view PDFs) requires Java 1.4 or later to run, although the actual PDF to bitmap
conversion will run under Java 1.3.
</p><p>
If you're trying to rasterize a PDF that does not have all it's fonts embedded, the
viewer will use the fonts available to Java to try and pick an appropriate one to
substitute. For Chinese, Japanese and Korean text in particular it is important to
have a suitable font available, or no text will be displayed.
</p><p id="ParserTIFF">
The top level class for all of this is <code>PDFParser</code>, which can either be used
directly or as a way to instantiate <code>PageParser</code> or <code>PageExtractor</code>
objects for parsing each individual page object. A very simple example here shows how to
convert a multi-page PDF to a multi-page TIFF.
</p><pre class="example" id="exampleParserTIFF">
import java.io.*;
<b>import org.faceless.pdf2.*;</b>
public class PDFtoTIFF {
public void main(String[] args) throws IOException {
PDFReader reader = new PDFReader(new File(args[0]));
PDF pdf = new PDF(reader);
FileOutputStream out = new FileOutputStream("PDFtoTIFF.tiff");
<b>PDFParser parser = new PDFParser(pdf);</b>
<b>parser.writeAsTIFF(out, 72, PDFParser.RGB);</b>
out.close();
}
}
</pre><p class="caption">Example 29 - Converting a PDF to TIFF</p>
<p>
The two bold lines show the <code>PDFParser</code> class in use - first, it's
created from the <code>PDF</code> object, then the PDF is converted to a 72dpi RGB TIFF
and written to a file. Simple.
</p>
<h2 id="ParserPrint">Printing a PDF</h2>
<p>
There are two printing models in Java: <code>Printable</code> jobs (which are single
page print jobs) and <code>Pageable</code> jobs, for multi-page jobs. The
<code>PDFParser</code> class implements <code>Pageable</code>, which means the entire
document can be printed easily. Alternatively the <code>PageParser</code> object
implements <code>Printable</code> so individual pages can be printed as necessary.
Here's a comprehensive example demonstrating both approaches - an individual
page can be printed using the <code>Printable</code> interface,
or a range of pages can be printed using the <code>Pageable</code> approach.
</p><pre class="example" id="exampleParserPrint">
import java.io.*;
import java.awt.print.*;
import javax.print.*;
import javax.print.attribute.*;
import javax.print.attribute.standard.*;
import org.faceless.pdf2.*;
// Usage is either
//
// java PrintPDF filename.pdf To print the entire document
// java PrintPDF filename.pdf num To print the page "num"
// java PrintPDF filename.pdf num1 num2 To print the pages "num1" to "num2"
//
public class PrintPDF
{
public void main(String[] args) throws IOException, PrinterException
{
PDFReader reader = new PDFReader(new File(args[0]));
PDF pdf = new PDF(reader);
<b>PDFParser parser = new PDFParser(pdf);</b>
PrintRequestAttributeSet printAttributes = new HashPrintRequestAttributeSet();
printAttributes.add(OrientationRequested.PORTRAIT);
MediaPrintableArea area = new MediaPrintableArea(0,0,210,296, MediaPrintableArea.MM);
printAttributes.add(area);
PrinterJob job = PrinterJob.getPrinterJob();
if (args.length==1) { // Print the whole document
<b>job.setPageable(parser);</b>
} else if (args.length==2) { // Print a single page
int pageno = Integer.parseInt(args[1]);
<b>PagePainter painter = parser.getPagePainter(pageno);</b>
<b>job.setPrintable(painter);</b>
} else if (args.length==3) { // Print a range of pages
int firstpage = Integer.parseInt(args[1]);
int lastpage = Integer.parseInt(args[2]);
PageRanges range = new PageRanges(firstpage, lastpage);
printAttributes.add(range);
<b>job.setPageable(parser);</b>
}
job.print(printAttributes);
}
}
</pre><p class="caption">Example 30 - Printing a PDF</p>
<p>
This example can be compiled and run, and will print a PDF specified on the command line to
the default printer. It uses the Java 1.1 printing API, which works but is slightly less
flexible than the new <code>javax.print</code> API added in Java 1.4. The
<code>PrintPDF.java</code> example supplied in the <code>example</code> directory shows how
to use the 1.4 API. Note that <b>not all PDF's allow printing</b> - we honor the usage
flags set on the document, and will throw an Exception if a PDF cannot be printed.
</p>
<h2 id="ParserTextExtraction">Text Extraction</h2>
<p>
Text extraction from a PDF was added in version 2.6.2, and is done via the
<code>PageExtractor</code> class. You can get one of these by calling
<code>PDFParse.getPageExtractor</code> for the appropriate page, and once you have one you
can extract text, images and so on. Here's a simple example:
</p><pre class="example" id="exampleParserTextExtraction">
PDFParser parser = new PDFParser(pdf);
for (int i=0;i<pdf.getNumberOfPages();i++) {
<b>PageExtractor extractor = parser.getPageExtractor(i);</b>
System.out.println(<b>extractor.getTextAsStringBuffer()</b>);
}
</pre><p class="caption">Example 31 - Extracting text from a PDF</p>
<p>
As you can see there's not much to it. The <code>getTextAsStringBuffer</code> method
attempts to extract and format the text in an <i>approximation</i> of the layout used on
the page. Text Extraction from PDF is not an exact science for a number of reasons,
including:
</p><ul>
<li>
Fonts may have no Unicode information or be encoded incorrectly, making it impossible to
convert back to text
</li>
<li>Text may be rendered as an image, making extraction impossible</li>
<li>
Layout may rely on visual features of the glyphs. Determining how much space is between
the end of one glyph and how much is before the start of the next (and whether it's a
layout feature or an inter-word space) is not always obvious.
</li>
<li>
When determining layout, features like superscript or subscript, overlaid or rotated text
cannot be accurately represented in plain text.
</li>
</ul><p>
For this reason results cannot be guaranteed as 100% accurate. Having said that most modern
PDFs can have their content extracted 100% reliably, with layout approximating the PDF as
closely as possible in plain text. Other methods in the <code>PageExtractor</code> class
allow the list of text objects to be returned as a Collection, which not only provides
information on exact page position, color and font, but can be modified to improve the text
extraction process (for example, if you know you don't want any rotated text to be
extracted, you can delete all the rotated text objects before running
<code>getTextAsStringBuffer</code>.
</p>
<h2 id="ParserImageExtraction">Image Extraction</h2>
<p>
As well as extracting text from the PDF, if the PDF allows it it's possible to extract
bitmap images as well. This is done via the <code>PageExtractor.getImages</code> method,
which returns a collection of Image objects used in the PDF, including their position on
the page, resolution and a <code>java.awt.image.BufferedImage</code>. This
<code>BufferedImage</code> can be saved as a PNG, JPEG or similar using the
<code>javax.imageio</code> classes. Here's a simple example which saves all the images
out to a file. Notice how we check for duplicates - images may be used more than once.
</p><pre class="example" id="exampleParserImageExtraction">
1. Set all = new HashSet();
2. PDFParser parser = new PDFParser(pdf);
3.
4. for (int i=0; i<pdf.getNumberOfPages(); i++) {
5. PageExtractor extractor = parser.getPageExtractor(i);
6. Collection images = extractor.getImages();
7. for (Iterator j=images.iterator(); j.hasNext();) {
8. PageExtractor.Image pageimage = (PageExtractor.Image)j.next();
9. BufferedImage image = pageimage.getImage();
10. if (!all.contains(image)) {
11. all.add(image);
12. File file = new File("image"+(all.size())+".png");
13. ImageIO.write(image, "png", file);
14. }
15. }
16. }
</pre><p class="caption">Example 32 - Extracting images from a PDF</p>
<pbr/>
<h1 id="AppendixA">Appendix A - Warning messages</h1>
<p>
A number of warnings are written to <code>System.err</code> by default if unexpected (but not
fatal) events occur. These can be turned off individually by setting the System property
<tt>org.faceless.pdf2.warning.XXX</tt> to any not null value, where <code>XXX</code> is the warning code, or all
the warnings can be disabled by setting the <tt>org.faceless.pdf2.warning.*</tt> property.
Be sure you know what you're doing though - they're printed for a reason.
</p>
<table class="defns">
<tr><td>AC1</td><td>No named action. A reference to a named action is stored in the document,
but an action with that name doesn't exist. The action is replaced with a "dummy" action that
does nothing.
</td></tr>
<tr><td>AN1</td><td>No rectangle for annotation. An annotation has been created but not
positioned on the page. It will remain but will have a rectangle of (0,0,0,0), making it
effectively invisible in Acrobat. Generally speaking you'll want to set a rectangle before
saving the PDF.
</td></tr>
<tr><td>AR1</td><td>No such object. The same as RF1.
</td></tr>
<tr><td>BC1</td><td>The BarCode has been created with parameters outside the acceptable range.
You barcode may still scan with some equipment, but it's not guaranteed to with all. Generally
this is because the code is too small, so you'll need to enlarge it if it's not scanning
correctly.
</td></tr>
<tr><td>CS1</td><td>JRE has buggy ColorSpace handling. A number of older Java runtimes (in our
tests, mainly those by IBM) have very, very poor implementations of the standard java.awt.color
package, with tendencies to throw everything from Exceptions to JNI errors. We work around
these as best as we can, but this is to let you know that you've got one of those JREs.
</td></tr>
<tr><td>CS2</td><td>The embedded ICC profile cannot be parsed for some reason, and the
alternate space will be used. Color Reproduction for the affect object won't be quite as
accurate as it should be but otherwise, theoretically, no difference should be noticed.
</td></tr>
<tr><td>E11</td><td>No unicode character for glyph 0xNN. You'll see this occasionally with Type 1
fonts that define characters that aren't in the mapping we have from glyph name to Unicode value.
Often these are symbol characters, or occasionally misnamed regular or punctuation characters. We
assign these characters an arbitrary position in the private range (U+EF00 to U+EFFF).</td></tr>
<tr><td>E12</td><td>No name for byte 0xNN. Caused by trying to read a form field containing a
corrupt value. The result is that the value of the field will contain some 0x0000 characters
instead of the correct ones.</td></tr>
<tr><td>E13</td><td>No Unicode character for name NNNN. This would be caused by trying to read a
form field containing a corrupt value. The result is that the value of the field will contain some
0x0000 characters instead of the correct ones.</td></tr>
<tr><td>E21</td><td>No Unicode character for glyph 0xNN. This would be
caused by trying to read a form field containing a corrupt value. The result is that the value of the
field will contain some 0x0000 characters instead of the correct ones.</td></tr>
<tr><td>F1</td><td>Field has no name. Several problems can and do occur with disturbing frequency in
Acrobat, often when a form is deleted - sometimes the job isn't finished properly. This particular
warning indicates that a field has no name and is going to be deleted. As described in FE3,
dangling fields are common, and if it has no name you can't interact with it in Acrobat anyway, so it's
not doing you any good keeping it around.
</td></tr>
<tr><td>F2</td><td>Widget has no name. A variation on the same theme as F1.</td></tr>
<tr><td>F3</td><td>Widget has no parent. Another variation on the same theme as F1.</td></tr>
<tr><td>F4</td><td>Fields point to orphan field. Yet another variation of the same.</td></tr>
<tr><td>F5</td><td>We can't imagine how this particular one could occur, but this warning
is here just in case. If it happens, we'd like to see your document!</td></tr>
<tr><td>FE1</td><td>Annotation for field has not been assigned to a page. Every form element may have
annotations, but each one of those has to be on a page. If you create an annotation but don't set it's
page, it's no use to anyone, and this warning is thrown when the document is written to show that it's
being removed.</td></tr>
<tr><td>FE2</td><td>Annotation for field is on another PDF's page. Like the error above, but this
normally occurs when you've been moving pages around between documents. If document A has a page and
one form field with an annotation on that page, and then you move the page to document B, when you try
and render document A, your form element has an annotation on page no longer in the document. Like FE1,
this warning is thrown and the annotation removed.
</td></tr>
<tr><td>FE3</td><td>Document still contains reference to deleted form field. This isn't too uncommon.
It usually occurs after flattening a documents form or after deleting a field from the form. What it
means is that even though the field isn't included in the form anymore, somewhere else in the document
there is a pointer to it, maybe in an action or in the "logical structure" information that is added by
Acrobat for it's own purposes. These kind of "dangling fields" are left around by Acrobat all the time -
we repair them quietly when a document is loaded - and although depending on context they could in theory
cause a problem, in practice we've never seen it happen.
</td></tr>
<tr><td>FN1</td><td>Skipping unknown character 0xNN. This is the most likely one you'll see. It means
you're trying to display a character which isn't in the font. With most of the emails we get about
this one, the character is 0x09 - the tab character. A tab cannot be displayed simply by including it
in a line of text! For a start, with a variable width font we've no idea how wide it should be.
Please see the <code>addTab</code> method in the <code>LayoutBox</code> class for a better way.
</td></tr>
<tr><td>IM1</td><td>Unable to extract ICC profile from PNG. Could be because the PNG has some corruption,
or because you've got the problem described for the CS1 warning.
</td></tr>
<tr><td>IM2</td><td>Unable to extract ICC profile from JPEG. Same as IM1 but for JPEGs
</td></tr>
<tr><td>IM3</td><td>CMYK JPEGs have trouble printing under Java 1.3. Due to bugs in the Java AWT code,
CMYK JPEGs are not handled well at all. In Java 1.4 we're able to recode them with values that work
using the <code>javax.imageio</code> package, but under Java 1.3 this isn't available and you'll see
CMYK JPEGs come out inverted. Install <code>javax.imageio</code> or upgrade to Java 1.4. Or stick with RGB.
</td></tr>
<tr><td>LB1</td><td>Can't display 0xNN. This is the most likely one you'll see. It means you're trying to display
a character which isn't in the font. With most of the emails we get about this one, the character is
0x09 - the tab character. A tab cannot be displayed simply by including it in the text!
For a start, with a variable width font we've no idea how wide it should be. Please see the <code>addTab</code>
method in the <code>LayoutBox</code> class for a better way.
</td></tr>
<tr><td>LB2</td><td>General text error. This could be caused by a number of reasons, but probably
relating to some issue in the font or encoding. One possible reason for this is trying to display more than 255
different characters in a single byte font. Take a good look at the font you've picked for the job
and what you're doing with it. Either way, if you see this message, there will be some text missing
from your document when it's written.
</td></tr>
<tr><td>MP1</td><td>No such object. The same as AR1.
</td></tr>
<tr><td>OT1</td><td>OpenType font has restrictions on embedding. The font author has explicitly stated
that the font is not allowed to be embedded without prior permission from them. We will embed the font
anyway, but be aware that fonts are copyrighted material and that you will need to obtain permission
from the font author and publisher legally
</td></tr>
<tr><td>OT2</td><td>No POST name for 0xNN. For single byte OpenType fonts, each character is required
to have a PostScript name. Some (arguably) corrupt fonts are missing some, which means that even though
the glyph is in the font you've chosen, you can't access it. This message is letting you know which
ones. You could always try embedding the font using 2 bytes per glyph to get around it.
</td></tr>
<tr><td>PD1</td><td>Removing invalid annotation. You're loading a PDF with some sort of corrupt
annotation or an invalid annotation list on one of the pages.
</td></tr>
<tr><td>PD2</td><td>Removing invalid widget annotation. You're loading a PDF with some sort of corrupt
annotation or an invalid annotation list on one of the form elements.
</td></tr>
<tr><td>PD3</td><td>Widget referenced from page but not form. Unfortunately reasonably common, this is
another case where Acrobat has almost certainly deleted a form field but not it's annotation. This warning
is to let you know we're finishing the job.
</td></tr>
<tr><td>PD4</td><td>No Form Field. You're importing an FDF that is trying to set a value in a form
field that doesn't exist in this document. This could indicate you're importing the wrong FDF or that you're
importing it into the wrong form, or maybe a later/earlier version of the same form.
</td></tr>
<tr><td>PD5</td><td>Invalid date field. The CreationDate or ModDate stored in the "Info" dictionary
is invalid. As you would expect this prevents the end user from identifying when the document was
created or modified, but other than that there are no side effects.
</td></tr>
<tr><td>PD6</td><td>Invalid XMP Metadata. The XMP Metadata is either invalid XML or doesn't match
the XMP specification. You can still read and write the metadata manually, but no automatic
updates will be performed on the data - it will not be kept in sync with the Info dictionary
as controlled by PDF.setInfo(). This warning is new in 2.6.2 - prior to that the XMP metadata
wasn't parsed at all.
</td></tr>
<tr><td>PG1</td><td>Annotation is part of another PDF's form. The opposite of FE2, this occurs when
in the situation described for FE2, you try and render document B. It's saying that a widget on this
page is actually the widget for a field in another document. Since a Widget has to have a field, we're
not going to render it and it gets deleted.
</td></tr>
<tr><td>PG2</td><td>Page has no size specified. We see this rarely in poorly constructed PDFs, and
the only reason we're not flagging it as an outright error is because Acrobat can display them. We
have to pick an arbitrary page size, which is typically Letter or A4 depending on the locale.
</td></tr>
<tr><td>RD1</td><td>Can't find "startxref". This is caused either by a truncated PDF, or by a PDF with
loads of junk at the end. A PDF should always end with the "%%EOF" tag, and just before that we need
to find the word "startxref". If we can't find it we ignore the xref table and scan the document - exactly
what Acrobat does when it says it's "Repairing" a PDF that's being read in. This isn't a problem unless
the resulting PDF isn't what you expected, which could happen when documents with multiple versions are
loaded.
</td></tr>
<tr><td>RD2</td><td>Can't find "startxref" again. The same as RD1.
</td></tr>
<tr><td>RD3</td><td>General xref table error. The most common version of the same error described in RD1,
this is caused by a corrupt cross-reference table. As for RD1/2, the PDF is then scanned to recreate the
table.
</td></tr>
<tr><td>RD4</td><td>Can't find N/N, got NNN. An indirect object is not in the PDF where it should be. This
is fairly serious, but like RF1, you might get lucky and find your document is usable none-the-less.
It all depends on what is missing.
</td></tr>
<tr><td>RD5</td><td>Stream is NNN bytes too long. This is more common than we'd like, mainly due to the
incorrect length calculations in some inferior PDF generation routines. If NNN is small that's probably
it, if it's big you've probably got a badly corrupt PDF and should consider yourself lucky to have got
this far without an exception!
</td></tr>
<tr><td>RD6</td><td>Stream is NNN bytes too short. The other side of RD5, but generally less serious.
Usually not a problem at all, just an indicator of poor PDF generation by someone.
</td></tr>
<tr><td>RF1</td><td>No such object. Something in your PDF is pointing to a missing object. This is the
most commonly seen warning (even Distiller frequently produces these documents), but whether it's
something to worry about depends on what's missing. PDFs, like people and engines, have lots of parts
you can remove without any noticeable difference. If the document looks correct then the missing piece
probably wasn't important.
</td></tr>
<tr><td>SG1</td><td>Certificate expired or not by VeriSign. When signing a digital signature destined
for the VeriSign plugin, this warning is to let you know that your signature is most likely going
to be invalid, for one of the specified reasons.
</td></tr>
<tr><td>ST1</td><td>Specified font not in form. As it says, a PDF has been loaded that contains a
form field that is to be displayed in a certain font - but that font isn't specified in the form.
How Acrobat managed to display it in the first place, we don't know, so we're substituting Helvetica.
If this is a poor choice, you can set the style by calling the <code>setTextStyle</code> method
on the appropriate <code>WidgetAnnotation</code>
</td></tr>
<tr><td>UP1</td><td>Corrupt Bookmark. A Bookmarks parent/child/next/previous marker points to
something that isn't a bookmark, or that just isn't there at all. You may lose a few bookmarks, but
the corruption will be repaired as best as we can.
</td></tr>
<tr><td>UP5</td><td>Missing named action. A "named" action is missing in the document. At worst this
will prevent a hyperlink from working, as the links action is converted to a no-op </td></tr>
<tr><td>UP6</td><td>Identical to UP5</td></tr>
</table>
<h1>Acknowledgments</h1>
<p>
Acrobat, AcroForm, Acrobat Forms, PDF, Portable Document Format, Type 1 Font, PostScript and XMP are trademarks of Adobe Corporation, Inc.
Java is a trademark of Sun Microsystems, Inc.
Unicode is a trademark of Unicode, Inc.
TrueType is a trademark of Apple Computer, Inc.
PANTONE is a trademark of the Pantone corporation, Inc.
<br/>
<br/>
Copyright (C) 2005 Big Faceless Organization. Created with the Big Faceless Report Generator.
</p>
</body>
</pdf>