Documents for PDF .NET Edition
Features / Layers
In This Topic
    Layers
    In This Topic

    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:

    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:

    1. Create and name layers by using the AddLayer method of OptionalContentProperties class.
    2. To begin drawing on a specific layer, call the BeginLayer method of GcPdfGraphics, specifying the target layer's name.
    3. Add content to the layer by using any of the GcPdfGraphics' Draw* methods (e.g. DrawString).
    4. To end drawing on the current layer, call the EndLayer method of GcPdfGraphics.
    5. Similarly, you can add content to other layers by using the BeginLayer/EndLayer methods and drawing on those other layers.
      C#
      Copy Code
      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:

    1. Create layer or layers as described above, storing the reference to the created layer object returned by the AddLayer method.
    2. Create a FormXObject (see FormXObject).
    3. Set the Layer property of the FormXObject to the layer you want the FormXObject to be associated with.
      C#
      Copy Code
      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.

    C#
    Copy Code
    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:

    C#
    Copy Code
    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:

     

    Note: The current version of GcDocs PDF Viewer does not allow visibility control of individual PDF Layers. To show or hide layers, open documents in Acrobat viewer.

    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.