PDF documents have the ability to place particular graphics in layers. When they do, it becomes possible to select certain layers for viewing in a viewer. This feature is often very useful for complex drawings so that users can restrict the view to the parts that they are interested in. The image below shows a typical example; this pdf contains two layers: and image layer (which is active) and a grid layer (which is inactive)
PDF documents have the ability to place particular graphics in layers. When they do, it becomes possible to select certain layers for viewing in a viewer. This feature is often very useful for complex drawings so that users can restrict the view to the parts that they are interested in. The image below shows a typical example; this pdf contains two layers: and image layer (which is active) and a grid layer (which is inactive).
Layers in PDF
So how do layers work in PDF? Despite their name, layers are not actually layers. Adobe calls them that way, but internally layers are optional content. The contents of a single layer are not stored in one collection at a particular z-order in the file. Instead, the content of a single layer may be located at various places in the file. What is shown on top is what happens to be drawn last. Temporal order defines the z-order. This is the case for all graphics in a PDF file, and layers are no exception. This means that one part of a layer may be drawn on top, while another part of the same layer is drawn at the back.
There are two structures in the PDF format related to layers:
- One defines a name for each layer.
- One associates particular graphics with a layer using the name above.
PDFKit.NET has support for PDF layers as well. One of our most basic design principles is that one should not try to abstract away too much from the original format. Certain abstractions may look wise in the beginning, but at some point they will start to hinder you. And of course, one needs to balance this. There is no golden rule.
We have chosen to have the layer support in PDFKit.NET closely follow the way that layers are present in PDF as described above. There are two places where you will encounter them in PDFKit.NET.
- TallComponents.PDF.Shapes.LayerShape: This is basically a collection that you can put shapes in. These shapes then become part of that layer.
- TallComponents.PDF.Document.Layers: This is a collection of layers that are present in the document. In essence these are layer names.
The Layer collection in the document defines the names, whereas the LayerShape defines the association. This also means that there can be multiple LayerShapes that are associated with the same Layer.
The following code shows how to use PDFKit.NET to put graphics in a particular layer:
// create a Drawing and make it occupy all space within the margins of the page
ShapeCollection shapes = new ShapeCollection( 100, 100, 400, 400 );
page.Overlay.Add( shapes );
// Create layers
Layer gridLayer = new Layer("Grid");
LayerShape gridLayerShape = new LayerShape(gridLayer);
Layer graphicsLayer = new Layer("Graphics");
LayerShape graphicsLayerShape = new LayerShape(graphicsLayer);
// coordinate (0, 0) lies at the bottom left of the shapes.
// draw a grid of 25 x 25 points
Pen gridPen = new Pen( System.Drawing.Color.LightGray, 1 );
for( double x = 0; x < shapes.Width; x += 25 )
for( double y = 0; y < shapes.Height; y += 25 )
// Draw the lines
gridLayerShape.Add(new LineShape(0, y, shapes.Width, y, gridPen));
gridLayerShape.Add(new LineShape(x, 0, x, shapes.Height, gridPen));
// Add axis numbering
gridLayerShape.Add(new TextShape(0, y, y.ToString(), Font.Helvetica, 8));
gridLayerShape.Add(new TextShape(x, 0, x.ToString(), Font.Helvetica, 8));
// add a line
graphicsLayerShape.Add(new LineShape(25, 25, 75, 50));
// add an ellipse
graphicsLayerShape.Add(new EllipseShape(150, 50, 50, 25));
// add a rectangle
graphicsLayerShape.Add(new RectangleShape(250, 25, 75, 50, new Pen(System.Drawing.Color.Black), new SolidBrush(System.Drawing.Color.Yellow)));
Removing a Layer
A consequence of this design decision is that it is relatively difficult to remove layers. If you remove a Layer from Document.Layers, all you do is basically removing a layer name. The Graphics that were associated with that name will then simply become disconnected from that layer and become part of the “ordinary” graphics of the document. And this means that you will no longer be able to make then invisible. If you do want to remove a layer from a page, you will have to call Page.CreateShapes() for that page, and remove all the LayerShapes that are associated with that layer name.
So there you have it: PDF documents are not like Ogres.