2.25 Layers or Optional Content

The PDF specification document (section 4.10) defines optional contents as follows. “Optional content (PDF 1.5) 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.”

Adobe Acrobat viewer has navigation panels on the left side of the screen. One of them is the layers panel. If a PDF document uses layers, the layers control switches will be displayed in this panel. The user can display or hide items that were attached to these layer controls.

Adding layers to your PDF document. The full example is given in LayersExample.cs. In addition OtherExample.cs has examples of using layers to control images and annotations.

Create the main layers control object. One per document.

// create a layers control object and give it a name.
// only one object like that is allowed.
// The name will be displayed in the layer panel.
PdfLayers Layers = new PdfLayers(Document, "PDF layers group");

Set the list mode option. The default is all pages

// List mode
Layers.ListMode = ListMode.AllPages; // default

// or
Layers.ListMode = ListMode.VisiblePages;

Create one or more layers objects. Each one will correspond to one check box on the layer panel. Each one can control one or many displayed items.

// create one or more layer objects
PdfLayer LayerName = new PdfLayer(Layers, "Layer name");

A number of layers can be combined into radio buttons group. One group of radio buttons can be all off or just one layer on.

// Optionally combine three layers into
// one group of radio buttons
LayerName1.RadioButton = "Group1";
LayerName2.RadioButton = "Group1";

Set the order of layers in the layer pane. If DisplayOrder method is not used, the program will list all layers specified above on the same main level. If DisplayOrder method is used, all layers must be included The list of layers can have sub-groups with optional name

// display order
Layers.DisplayOrder(LayerName1);
Layers.DisplayOrder(LayerName2);
Layers.DisplayOrder(LayerName3);
Layers.DisplayOrderStartGroup("Sub Group");
Layers.DisplayOrder(LayerName4);
Layers.DisplayOrder(LayerName5);
Layers.DisplayOrder(LayerName6);
Layers.DisplayOrderEndGroup();

Define an area within contents stream to be controlled by layer

// contents stream start layer marker
Contents.LayerStart(LayerName1);

// your contents methods to be
// controlled by LayerName1

// end of LayerName1 area
Contents.LayerEnd();

Control an image or annotation directly. The image can be anywhere within the document.

// image or annotation control
QREncoder QREncoder = new QREncoder();
QREncoder.ErrorCorrection = ErrorCorrection.M;
QREncoder.Encode("Some data");
PdfImage QRImage = new PdfImage(Document);
QRImage.LayerControl = LayerName1;
QRImage.LoadImage(QREncoder);