Manage Visibility of Layers (Optional Content Groups)
- 5 minutes to read
Layers: Overview
Complex PDF documents such as CAD drawings, technical construction plans, layered artwork, maps, or multi-language documents can contain optional content (layers). Layers in a PDF document allow you to selectively view or hide specific content sections. The main purpose of layers is to control the visibility of graphics objects rendered in a PDF document in different states (when you view or print a PDF document). For example, layer visibility can be helpful in the following cases:
- A PDF document with multi-lingual content that can be displayed conditionally.
- A PDF document that contains animation that appears on a separate layer.
- License agreement in a PDF document that needs to be agreed upon before the content can be viewed.
- A PDF document containing a watermark that may not show on screen but is always printed and exported to other applications.
- A PDF document that contains details of a product design.
Set Layer Visibility
The PdfOptionalContentGroupVisibility class contains visibility settings that correspond to a layer (the PdfOptionalContentGroup object). All PdfOptionalContentGroupVisibility objects are stored in a PdfOptionalContentGroupVisibilityCollection object and can be accessed with the PdfDocumentFacade.OptionalContentVisibility.Groups property by index.
Use the PdfOptionalContentGroupVisibility.Visible property to show or hide a layer.
Important
A PDF document stores only default optional content configuration. This means that layer visibility is not preserved when you save the document. Visibility settings are applicable only when you preview the document in a PDF Viewer component, or print the document, or export it to an image.
The following code snippet hides two layers in the “PdfLayers.pdf” document and displays the third 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");
// Set visibility settings for each layer contained in a document.
processor.DocumentFacade.OptionalContentVisibility.Groups[0].Visible = false;
processor.DocumentFacade.OptionalContentVisibility.Groups[1].Visible = false;
processor.DocumentFacade.OptionalContentVisibility.Groups[2].Visible = true;
// Print the document.
DXBitmap bitmap = processor.CreateDXBitmap(1, 1000);
PdfPrinterSettings pdfPrinterSettings = new PdfPrinterSettings();
processor.Print(pdfPrinterSettings);
}
}
Control Layer Visibility
A PDF document may contain default configuration (the PdfOptionalContentProperties.DefaultConfiguration property value) that specifies “usages” (layer settings that depend on state). For example, the configuration can specify that a layer hidden when you view the document, yet is visible on a printed copy.
The following usage categories are available:
- View - settings applied to the layer in view state (when you view a document in a viewer).
- Print - settings applied to the layer in print preview or when you print a document.
- Export - settings applied to the layer when you export a document.
- Zoom - settings applied to the layer according to the zoom level.
- Language - language culture settings applied to the layer.
You can manage layers visibility when you view or print the document. To ensure your current visibility settings are applied correctly, use the PdfOptionalContentVisibility.ActiveUsages property. ActiveUsages allows you to specify the category for which you want to enable layer settings. 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. Set ActiveUsages to none to disable all default settings and apply only the current settings.
The following image demonstrates a document with three layers. All three layers are visible in the default configuration when you view the document. The second layer also contains default print settings. When you print the document, the second layer remains visible even if you set its Visible property to false:
The following code snippet shows how to hide the second layer when you print the document described above:
using DevExpress.Pdf;
using System;
using System.Linq;
using DevExpress.Drawing;
static void Main(string[] args) {
using (PdfDocumentProcessor processor = new PdfDocumentProcessor()) {
processor.LoadDocument("PdfLayersPrintUsage.pdf");
// Hide the second layer.
processor.DocumentFacade.OptionalContentVisibility.Groups[1].Visible = false;
// Disable default settings for layers.
processor.DocumentFacade.OptionalContentVisibility.ActiveUsages = PdfOptionalContentUsageCategories.None;
// Print the document to apply the current setting.
DXBitmap bitmap = processor.CreateDXBitmap(1, 1000);
PdfPrinterSettings pdfPrinterSettings = new PdfPrinterSettings();
processor.Print(pdfPrinterSettings);
}
}
As a result, the second layer is hidden when you print the document:
When you view the document, you can also override default settings for an individual layer. PdfOptionalContentGroupVisibility.ManualVisibilityOverride set to true indicates that your current visibility settings have higher priority than default configuration. For example, a PDF document can contain a layer that changes its visibility based on the zoom level. If you want to display the layer regardless of the zoom level, set both Visible and ManualVisibilityOverride to true for that layer.
Note
The ManualVisibilityOverride property is in effect only when you view a document. The default configuration will be applied when you print a document.