Layers

The layers (optional content) in a PDF document allow you to selectively view or hide the specific content sections. The main purpose of layers is to control the visibility of graphics objects rendered in a PDF document. A few examples where PDF layers can be particularly useful, are:

PDF document containing multi-lingual content, each in different layers.
PDF document containing animation that appears on a separate layer.
License agreement in a PDF document which needs to be agreed upon before the content can be viewed.
PDF document containing a watermark, which may not show onscreen but is always printed and exported to other applications.
PDF document containing details over a product design.

GcPdf allows you to create layers, associate content (such as content stream, FormXObject and annotation) with different layers and set their properties. The OptionalContentProperties class provides various methods and properties which can be used to implement layers in PDF documents.

Create Layers in a PDF document

To create layers in a PDF and draw on them:

Create and name layers by using the AddLayer method of OptionalContentProperties class.
To begin drawing on a specific layer, call the BeginLayer method of GcPdfGraphics, specifying the target layer's name.
Add content to the layer by using any of the GcPdfGraphics' Draw* methods (e.g. DrawString).
To end drawing on the current layer, call the EndLayer method of GcPdfGraphics.

Similarly, you can add content to other layers by using the BeginLayer/EndLayer methods and drawing on those other layers.

GcPdfDocument doc = new GcPdfDocument();
doc.OptionalContent.AddLayer("Layer1");
doc.OptionalContent.AddLayer("Layer2");

var g = doc.NewPage().Graphics;
g.BeginLayer("Layer1");
g.DrawString("Layer1", new TextFormat() { Font = StandardFonts.Courier }, new PointF(10, 10));
g.EndLayer();

g.BeginLayer("Layer2");
g.DrawString("Layer2", new TextFormat() { Font = StandardFonts.Courier }, new PointF(10, 30));
g.EndLayer();
doc.Save("SimpleLayers.pdf");

The output of above code example will look like:

Create Layers and Associate FormXObject

A FormXObject can also be associated with a specific layer. The following code example demonstrates this:

Create layer or layers as described above, storing the reference to the created layer object returned by the AddLayer method.
Create a FormXObject (see FormXObject).

Set the Layer property of the FormXObject to the layer you want the FormXObject to be associated with.

GcPdfDocument doc = new GcPdfDocument();
var l1 = doc.OptionalContent.AddLayer("Layer1");
var l2 = doc.OptionalContent.AddLayer("Layer2");

var g = doc.NewPage().Graphics;

FormXObject fxo1 = new FormXObject(doc, new RectangleF(0, 0, 100, 100));
fxo1.Graphics.FillRectangle(new RectangleF(0, 0, 100, 100), Color.Blue);
fxo1.Graphics.DrawString(l1.Name, new TextFormat() { Font = StandardFonts.Courier }, new PointF(10, 10));
fxo1.Layer = l1;

FormXObject fxo2 = new FormXObject(doc, new RectangleF(0, 0, 100, 100));
fxo2.Graphics.DrawRectangle(new RectangleF(0, 0, 100, 100), Color.Blue, 4);
fxo2.Graphics.DrawString(l2.Name, new TextFormat() { Font = StandardFonts.Courier }, new PointF(10, 10));
fxo2.Layer = l2;

g.DrawForm(fxo1, new RectangleF(10, 10, 100, 100), null, ImageAlign.StretchImage);
g.DrawForm(fxo2, new RectangleF(150, 10, 100, 100), null, ImageAlign.StretchImage);
doc.Save("FormXObjectLayers.pdf");

The output of above code example will look like:

Create Layers and Associate Annotation

An annotation can also be associated with a specific layer. The below example code demonstrates this by setting the Layer property of the AnnotationBase class to the desired layer.

GcPdfDocument doc = new GcPdfDocument();
var l1 = doc.OptionalContent.AddLayer("Layer1");
var l2 = doc.OptionalContent.AddLayer("Layer2");

var p = doc.NewPage();

var ft = new FreeTextAnnotation();
ft.UserName = "UserName";
ft.Rect = new RectangleF(10, 10, 100, 100);
ft.Contents = $"Annotation from {l1.Name}";
ft.Layer = l1;
p.Annotations.Add(ft);

ft = new FreeTextAnnotation();
ft.UserName = "UserName";
ft.Rect = new RectangleF(150, 10, 100, 100);
ft.Contents = $"Annotation from {l2.Name}";
ft.Layer = l2;
p.Annotations.Add(ft);
doc.Save("AnnotationLayers.pdf");

The output of above code example will look like:

Set Layer Properties

You can use the Set* utility methods of the OptionalContentProperties class to change the various properties of different layers. The below example code demonstrates this:

GcPdfDocument doc = new GcPdfDocument();
using (FileStream fs = new FileStream("construction_drawing-final.pdf", FileMode.Open))
{
    doc.Load(fs);
    doc.OptionalContent.SetLayerLocked("Architecture", true);
    doc.OptionalContent.SetLayerInitialViewState("Equipment", LayerInitialViewState.VisibleWhenOn);
    doc.OptionalContent.Groups.FindByName("Electrical").Intent = new string[] { "Design" };
    doc.OptionalContent.SetLayerDefaultState("HVAC", false);
    doc.OptionalContent.SetLayerPrintState("Pipe", LayerPrintState.Never);
    doc.Save("SetLayerProperties.pdf");        
}

The output of above code example will look like:

Layer_Properties

Perform PDF Operations on Layer

In GcPdf, you can perform a particular PDF operation such as searching text, extracting text or drawing annotation on the specified layer. This can be achieved by using the ViewState class which allows to define environment settings and fetches the state of layer in the environment. To perform an operation on a specific layer, you can pass an instance of this class to method corresponding to that operation.

For instance, following sample code shows how to search a text in the specified layer of PDF document.

void FindInLayer(GcPdfDocument doc, string layer, string text, Color highlight)
{
    // Create a view state with just the specified layer visible:
    var viewState = new ViewState(doc);
    viewState.SetLayersUIStateExcept(false, layer);
    viewState.SetLayersUIState(true, layer);

    // Create a FindTextParams using our custom view state
    // so that the search is limited to the specified layer only:
    var ftp = new FindTextParams(text, false, false, viewState, 72f, 72f, true, true);

    // Find all occurrences of the search text:
    var finds = doc.FindText(ftp, OutputRange.All);

    // Highlight all occurrences on the specified layer only:
    foreach (var find in finds)
        foreach (var ql in find.Bounds)
        {
            var g = doc.Pages[find.PageIndex].Graphics;
            g.BeginLayer(layer);
            doc.Pages[find.PageIndex].Graphics.FillPolygon(ql, highlight);
            g.EndLayer();
        }
}

Remove Layer and Associated Content

While dealing with multi-layer PDF documents, sometimes you might want to choose whether or not to delete the associated content while removing a layer. GcPdf provides OptionalContent.RemoveLayer method which lets you choose whether to remove content associated with the layer while removing it. The method accepts removeContent property and array of the OptionalContentGroup objects as its parameters. To remove the content associated to a layer, you can also use Page.RemoveLayersContent method.

// Remove all layers except the last one with their content:
var layers = doc.OptionalContent.Groups.Take(doc.OptionalContent.Groups.Count - 1).ToArray();
doc.OptionalContent.RemoveLayers(true, layers);
// Remove the single remaining layer, leaving its content in place:
doc.OptionalContent.RemoveLayer(doc.OptionalContent.Groups[0]);

Limitation

GcPdf does not support layers when rendering the PDF document, meaning that there is no ability to hide layers. The complete content is rendered regardless of whether it belongs to any layer or not.