<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>iText Tutorial: Optional Content</title><meta name="Description" content="Add optional content to a PDF file."><meta name="Keywords" content="PDF, JAVA, iText, examples, optional content, OCG, Lowagie, Bruno"><link rel="stylesheet" href="./../../style.css" type="text/css"></head><body><a name="top" class="logo" href="http://www.lowagie.com/iText"><img src="http://www.lowagie.com/iText/images/logo.gif" border="0" alt="iText"></a><h1>Tutorial: iText by Example</h1><h2>Optional Content</h2><div id="content"><div id="sidebar"><a class="toc" href="./../../index.html#directcontent_optionalcontent">
Table of Contents
</a><div align="Center" class="small">Best viewed with:<br><script type="text/javascript"><!--
google_ad_client = "pub-0340380473790570";
google_ad_width = 180;
google_ad_height = 60;
google_ad_format = "180x60_as_rimg";
google_cpa_choice = "CAAQyaj8zwEaCIwcWMzeycafKMu293M";
//--></script><script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script></div><div class="sidetitle">Sections:</div><ul><li><a href="#inaction">In the book</a></li><li><a href="#ocg">Optional Content Groups</a></li></ul><br><br><div class="sidetitle">Examples:</div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/OrderedLayers.java">OrderedLayers</a><br><div class="description">Ordering Optional Content Groups</div><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/orderedlayers.pdf">orderedlayers.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/ContentGroups.java">ContentGroups</a><br><div class="description">Grouping Optional Content</div><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/contentgroups.pdf">contentgroups.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/OptionalContent.java">OptionalContent</a><br><div class="description">Changing the visibility using an Action</div><div class="small">Input:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/pngnow.png">pngnow.png</a></li></ul><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/optionalcontent.pdf">optionalcontent.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/NestedLayers.java">NestedLayers</a><br><div class="description">Nesting Optional Content</div><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/nestedlayers.pdf">nestedlayers.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/Automatic.java">Automatic</a><br><div class="description">Automatic grouping and nesting of Optional Content</div><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/automatic.pdf">automatic.pdf</a></li></ul></div><div class="example"><a class="source" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/Layers.java">Layers</a><br><div class="description">Zooming and radio groups</div><div class="small">Output:</div><ul><li><a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/layers.pdf">layers.pdf</a></li></ul></div><div class="example"><div class="small">ANT script (all examples):</div><ul><li><a href="./../../directcontent/optionalcontent/build.xml">
build.xml
</a></li></ul></div></div><div id="main"><a name="inaction"></a><div class="title">In the book:</div><div xmlns="http://www.w3.org/1999/xhtml" xmlns:site="http://www.lowagie.com/iText/site">
<p xmlns=""><a href="http://itext.ugent.be/itext-in-action/"><img src="http://itext.ugent.be/img/lowagie_3d.jpg" border="0" align="right"></a>
The examples in this free online tutorial will help you getting started
with iText. Note that most examples are two years old.
Some of the examples may be obsolete. Also the theory that
comes with the examples isn't always 100% accurate.
If you want more recent examples or if you want to know more
about the theoretical background of PDF and iText, please consult the book
<a href="http://itext.ugent.be/itext-in-action/">
"iText in Action".
</a>
Note that the first and the third chapter of the book
can be downloaded for free from <a href="http://www.manning.com/affiliate/idevaffiliate.php?id=223_53">http://manning.com/lowagie/</a></p><p>
More specifically:
<ul><li><a class="subtitle" href="http://itext.ugent.be/itext-in-action/chapter.php?chapter=12">
Chapter 12:
</a>Drawing to Java Graphics2D</li></ul></p>
</div><a class="top" href="#top">Go to top of the page</a><a name="ocg"></a><div class="title">Optional Content Groups:</div><div xmlns="http://www.w3.org/1999/xhtml">
Optional content is discussed in section 4.10 of the PDF Reference Manual:
<blockquote><i>Optional Content</i> refers to sections of content in a PDF
document that can be selectively viewed or hidden by document authors or
consumers. This capability is useful in items such as CAD drawings,
layered artwork, maps and multi-language documents.</blockquote>
Graphics that can be made visible/invisible dynamically are grouped in
<i>optional content groups</i>. Content that belongs to a certain group is visible
when the group is ON and invisible when the group is OFF.<br>
In iText, we call such groups 'layers'. You can create a
<a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfLayer.html">PdfLayer</a> object
and when adding content to a <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfContentByte.html">PdfContentByte</a>-object,
we are going to specify in which layer (= Content Group) the content should be shown (or hidden).
<pre xmlns="http://www.w3.org/1999/xhtml" class="commandline">PdfContentByte cb = writer.getDirectContent();
PdfLayer l = new PdfLayer("My Layer", writer);
cb.beginLayer(l);
// add content to 'My Layer' here
cb.endLayer();</pre>
You can combine different PdfLayers in a <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfLayerMembership.html">PdfLayerMembership</a>:
<pre xmlns="http://www.w3.org/1999/xhtml" class="commandline">PdfContentByte cb = writer.getDirectContent();
PdfLayer l1 = new PdfLayer("Layer 1", writer);
PdfLayer l2 = new PdfLayer("Layer 2", writer);
PdfLayerMembership m = new PdfLayerMembership(writer);
m.addMember(l1);
m.addMember(l2);
cb.beginLayer(m);
// add content to 'Layer 1' and 'Layer 2' here
cb.endLayer();</pre>
This is a simple example:
<div id="example">
Example: java
<a xmlns="" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/OrderedLayers.java">
com.lowagie.examples.directcontent.optionalcontent.OrderedLayers</a><br>Ordering Optional Content Groups: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/orderedlayers.pdf">orderedlayers.pdf</a><br></div>
As you see, you have a pane to your right in Acrobat Reader with all the available layers.
Two of them are grouped in 'A group of two'. You can click on the eye-symbol to make a layer invisible.<br xmlns="http://www.w3.org/1999/xhtml">
Remark that we have set the PDF version to 1.5 just after creating the writer (because OCG was only introduced since version 1.5)
and we have also set the Viewer Preferences to <span class="commandline">PageModeUseOC</span>.
<pre class="commandline">writer.setPdfVersion(PdfWriter.VERSION_1_5);
writer.setViewerPreferences(PdfWriter.PageModeUseOC);</pre>
Every writer object has a <a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfOCProperties.html">PdfOCProperties</a> dictionary.
You can get this dictonary with <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfWriter.html#getOCProperties()">getOCProperties()</a>
as is done in the example above.
Dictionaries are objects that are used a lot in PDF (other specific PDF objects are PdfArray, PdfString, PdfNull, PdfName, PdfNumber,...).
iText creates lots of these objects behind the scenes.
If you want to use the <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfOCProperties.html">PdfOCProperties</a> dictionary,
you have a chance to get a better understanding of the iText internals (this is an euphemism meaning it's rather complex stuff).
The code below gets the OC Properties from the writer, creates an ORDER-array and adds the layers l1, l2 and l3 to this order array,
with l2 and l3 inside a 'group of two':
<pre xmlns="http://www.w3.org/1999/xhtml" class="commandline">PdfOCProperties ocp = writer.getOCProperties();
PdfArray order = new PdfArray();
order.add(l1.getRef());
PdfArray group = new PdfArray();
group.add(new PdfString("A group of two", PdfObject.TEXT_UNICODE));
group.add(l2.getRef());
group.add(l3.getRef());
order.add(group);
PdfDictionary dict = new PdfDictionary();
dict.put(PdfName.ORDER, order);
ocp.put(PdfName.D, d);</pre>
Just take a look at the resulting PDF to see the effect:
<div id="example">
Example: java
<a xmlns="" href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/ContentGroups.java">
com.lowagie.examples.directcontent.optionalcontent.ContentGroups</a><br>Grouping Optional Content: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/contentgroups.pdf">contentgroups.pdf</a><br></div>
With some small changes, we can 'nest' the layers instead of grouping them:
<div id="example">
Example: java
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/NestedLayers.java">
com.lowagie.examples.directcontent.optionalcontent.NestedLayers</a><br>Nesting Optional Content: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/nestedlayers.pdf">nestedlayers.pdf</a><br></div>
You may find all this rather elaborate and complex.
I'm sorry, I've been pulling your leg in order to show how iText works.
There are far more simpler ways to order, group or nest OCGs:
just use the methods
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfLayer.html#createTitle(java.lang.String,%20com.lowagie.text.pdf.PdfWriter)">PdfLayer.createTitle</a>
and <a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfLayer.html#addChild(com.lowagie.text.pdf.PdfLayer)">PdfLayer.addChild</a>,
and iText will do all the difficult work for you.
<div id="example">
Example: java
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/Automatic.java">
com.lowagie.examples.directcontent.optionalcontent.Automatic</a><br>Automatic grouping and nesting of Optional Content: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/automatic.pdf">automatic.pdf</a><br></div>
You might want to take a look at the other methods in class
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfLayer.html">PdfLayer</a>:
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfLayer.html#setZoom(float,%20float)">PdfLayer.setZoom</a>
might be handy if you are drawing a map: you can specify between which maximum and minimum zoom factor the content should be visible.
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfLayer.html#setPrint(java.lang.String,%20boolean)">PdfLayer.setPrint</a>
if you want to add content that is intended for use in printing.
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfLayer.html#">PdfLayer.setOn</a> sets the initial visibility of the layer.
<a href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfLayer.html#setOnPanel(boolean)">PdfLayer.setOnPanel</a> sets the visibility of the layer in Acrobat's layer panel. If set to false the layer cannot be directly manipulated by the user.
These methods are used in this example:
<div id="example">
Example: java
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/Layers.java">
com.lowagie.examples.directcontent.optionalcontent.Layers</a><br>Zooming and radio groups: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/layers.pdf">layers.pdf</a><br></div>
There are lots of other methods in class PdfLayer. But let's look at one final example:
<div id="example">
Example: java
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/OptionalContent.java">
com.lowagie.examples.directcontent.optionalcontent.OptionalContent</a><br>Changing the visibility using an Action: see
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/optionalcontent.pdf">optionalcontent.pdf</a><br>
External resources for this example:
<a href="http://itext.ugent.be/library/com/lowagie/examples/directcontent/optionalcontent/pngnow.png">pngnow.png</a><br></div>
As you can see toggling layers can be done in the layers panel in Acrobat Reader,
but you can also make an action that changes the visibility status of the layers.
<pre xmlns="http://www.w3.org/1999/xhtml" class="commandline">ArrayList state = new ArrayList();
state.add("toggle");
state.add(l1);
state.add(l2);
state.add(l3);
state.add(l4);
PdfAction action = PdfAction.setOCGstate(state, true);
Chunk ck = new Chunk("Click here to toggle the layers").setAction(action);</pre>
The different possibilities are "ON", "OFF" or "Toggle" (see also the API for
<a xmlns="" href="http://itext.ugent.be/library/api/com/lowagie/text/pdf/PdfAction.html#setOCGstate(java.util.ArrayList,%20boolean)">PdfAction.setOCGstate</a>).
</div><a class="top" href="#top">Go to top of the page</a><div id="footer" xmlns="http://www.w3.org/1999/xhtml">
Page Updated: 2006/09/17 10:13:58
Copyright © 1999-2005
Bruno Lowagie<br><a href="http://www.lowagie.com/iText/">iText</a> is a Free Java-Pdf library by Bruno Lowagie and Paulo Soares.
</div></div></div><div class="commercial"><br><script type="text/javascript"><!--
google_ad_client = "pub-0340380473790570";
google_ad_width = 120;
google_ad_height = 600;
google_ad_format = "120x600_as";
google_ad_channel ="";
google_ad_type = "text_image";
google_color_border = "FFFFFF";
google_color_bg = "FFFFFF";
google_color_link = "1B09BD";
google_color_url = "100670";
google_color_text = "707070";
//--></script><script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script><br><br><div class="subtitle">Amazon books:</div><script type="text/javascript"><!--
document.write('<iframe src="http://rcm.amazon.com/e/cm?t=itisacatalofwebp&o=1&p=8&l=as1&asins=1932394796&fc1=000000&lc1=0000ff&bc1=<1=_blank&IS2=1&bg1=ffffff&f=ifr" width="120" height="240" scrolling="no" marginwidth="0" marginheight="0" frameborder="0" align="Center"></iframe>');
//--></script><a xmlns="" href="http://www.amazon.co.uk/exec/obidos/ASIN/1932394796/catloogjecom-21" class="amazonlinks">
amazon.co.uk-link
</a><br><br><script type="text/javascript"><!--
document.write('<iframe src="http://rcm.amazon.com/e/cm?t=itisacatalofwebp&o=1&p=8&l=as1&asins=0321304748&fc1=000000&lc1=0000ff&bc1=<1=_blank&IS2=1&bg1=ffffff&f=ifr" width="120" height="240" scrolling="no" marginwidth="0" marginheight="0" frameborder="0" align="Center"></iframe>');
//--></script><a href="http://www.amazon.co.uk/exec/obidos/ASIN/0321304748/catloogjecom-21" class="amazonlinks">
amazon.co.uk-link
</a><br><br><script type="text/javascript"><!--
document.write('<iframe src="http://rcm.amazon.com/e/cm?t=itisacatalofwebp&o=1&p=10&l=st1&mode=books&search=JAVA&=1&fc1=&lc1=<1=&bg1=&f=ifr" width="120" height="460" border="0" frameborder="0" style="border:none;" scrolling="no" marginwidth="0" marginheight="0"></iframe>');
//--></script><br><script type="text/javascript"><!--
document.write('<iframe src="http://rcm.amazon.com/e/cm?t=itisacatalofwebp&o=1&p=10&l=st1&mode=books&search=PDF&=1&fc1=&lc1=<1=&bg1=&f=ifr" width="120" height="460" border="0" frameborder="0" style="border:none;" scrolling="no" marginwidth="0" marginheight="0"></iframe>');
//--></script><br></div></body></html>
