Layers (Optional Content Groups)
- 4 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.
- A 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 PDF Viewer allows you to manage layer visibility when you view a document:
Important
The PDF Viewer does not save layer visibility changes, even if you save a separate copy of the document. Original visibility settings remain in effect and they control document appearance when a user opens the document to view its content, prints it, or exports it to an image.
User Interface
The Layers panel displays all layers contained in a document. To display a layer, click on its check box. Visible layers are marked with the eye icon.
If a layer has no check box or displays a lock icon, you cannot change its visibility:
Click the “Reset to Initial Visibility” command to reset layer settings and return to the initial document state.
Use PDF Facade API to Manage Layer Visibility
Important
The Universal Subscription or an additional Office File API Subscription is required to use Facade API in production code. Refer to the DevExpress Subscription page for pricing information.
Call the GetDocumentFacade method to obtain PdfDocumentFacade and manage layer visibility.
Use the PdfDocumentFacade.OptionalContentVisibility property to access PdfOptionalContentGroupVisibility objects. The PdfOptionalContentGroupVisibility class contains visibility settings that correspond to a layer (the PdfOptionalContentGroup object).
Use the PdfOptionalContentGroupVisibility.Visible property to show or hide a layer.
The following code snippet hides two layers in the “PdfLayers.pdf” document and displays the third layer:
using DevExpress.Pdf;
using DevExpress.XtraPdfViewer;
//...
PdfViewer viewer = new PdfViewer();
Controls.Add(viewer);
viewer.Dock = DockStyle.Fill;
viewer.LoadDocument("PDFLayers.pdf");
var facade = viewer.GetDocumentFacade();
facade.OptionalContentVisibility.Groups[0].Visible = false;
facade.OptionalContentVisibility.Groups[1].Visible = false;
facade.OptionalContentVisibility.Groups[2].Visible = true;
A layer can contain zoom settings. For example, a PDF document can contain a layer that changes its visibility based on the zoom level. If your code makes a layer visible, it may still disappear when users change the zoom level in the viewer. If you want to display a layer regardless of the zoom level, set both Visible and [PdfOptionalContentGroupVisibility.ManualVisibilityOverride] to true for that layer. The latter indicates that your current visibility settings have higher priority than the default configuration.
Use PDF Facade API to Configure State-Dependent Settings
Important
The Universal Subscription or an additional Office File API Subscription is required to use Facade API in production code. Refer to the DevExpress Subscription page for pricing information.
A PDF document may contain default configuration (the PdfOptionalContentProperties.DefaultConfiguration property value) that specifies “usages” (layer settings that depend on state).
The following usage categories are available:
- View
- Settings applied to the layer in view state (when you view a document in a viewer).
- 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.
In code, use the ActiveUsages property to specify which settings from the default configuration should be preserved. Set ActiveUsages to none to disable all default settings and apply only those you specified in code or in the UI.
For example, the configuration can specify that a layer is hidden when you view the document, but is visible on a printed copy:
The following code snippet disables all usages in layers and allows you to print the document as you specified:
using DevExpress.Pdf;
using DevExpress.XtraPdfViewer;
//...
PdfViewer viewer = new PdfViewer();
Controls.Add(viewer);
viewer.Dock = DockStyle.Fill;
viewer.LoadDocument("PDFLayers.pdf");
var facade = viewer.GetDocumentFacade();
facade.OptionalContentVisibility.ActiveUsages = PdfOptionalContentUsageCategories.None;
viewer.Print();
The following image illustrates the result:
