PDF Document API — Using Layers (Optional Content Groups) to Control Visibility of PDF Graphics Objects (v24.1)

Complex PDF documents such as CAD drawings, technical construction plans, layered artwork, maps, or multi-language documents are full of visual information. PDF layers are often used to simplify these documents and improve overall readability (layers allow you to selectively view/hide sections).

In this blog post, I'll introduce a couple of straightforward layer-related usage scenarios and show you how to use the DevExpress PDF Viewer and PdfDocumentProcessor (PDF Document APIs) to control layer visibility in your DevExpress-powered app (layer visibility support was introduced in v24.1). 

Control Layer Visibility

You can set PDF layer visibility by using the PdfOptionalContentGroupVisibility.Visible property for the appropriate layer or within the Layers panel of the DevExpress PDF Viewer. To display a layer, click its associated check box (visible layers are signified with an "eye" icon).

You can also manage layer visibility through the Document Facade API. When a layer is added to a document, a user must specify the default configuration (layer settings based on state). For example, your configuration can specify that a given layer is hidden when viewed, but visible when printed. When you load a document, you can obtain the default layer configuration (PdfOptionalContentProperties.DefaultConfiguration property value) and specify the category used to enable layer settings:

• View - settings applied to the layer in a view state (when you display a document in a viewer).
• Print - settings applied to the layer in print preview mode or when you print the document.
• Export - settings applied to the layer when you export a document.
• Zoom - settings applied to the layer based on zoom level.
• Language - language culture settings applied to the layer.

For example, if you set ActiveUsages to PdfOptionalContentUsageCategories.Print, only print settings from the default configuration are applied to layers when you print the document. Other default settings are automatically disabled. You can set ActiveUsages to none to disable all default settings and only apply current settings.

Use Case 1: Analyze Report Data from Different Perspectives

In this example, a PDF report with sales metrics includes multiple layers with comments for different people. You can control layer visibility within the PDF viewer when viewing the document. This allows you to display appropriate comments without increasing the number of report pages.

Use Case 2: Display Details when Zooming

In this instance, a PDF file with a map uses a different layer at 200% zoom (displays additional data).

Use Case 3: Label Documents when Printing

In this instance, the DevExpress logo is added to the printed document. The logo is placed on a separate layer and includes the following configuration settings:

it is hidden when you view the document but rendered when you print/export this document.

For this scenario, we enabled print usage for the configured layer:

using DevExpress.Pdf;
using System;
using System.Linq;
using DevExpress.Drawing;

static void Main(string[] args) {
    using (PdfDocumentProcessor processor = new PdfDocumentProcessor()) {
        processor.LoadDocument("PdfLayers.pdf");
        // Specify which settings from the default configuration will be applied for each layer contained in a document.
        processor.DocumentFacade.OptionalContentVisibility.ActiveUsages = PdfOptionalContentUsageCategories.Print;
        // Print the document.
        DXBitmap bitmap = processor.CreateDXBitmap(1, 1000);
        PdfPrinterSettings pdfPrinterSettings = new PdfPrinterSettings();
        processor.Print(pdfPrinterSettings);
    }
}

As I mentioned earlier, layer support was introduced in our v24.1 release cycle. Should you have any questions about this post or our PDF APIs/PDF Viewer components, please submit a support ticket via the DevExpress Support Center at your convenience.