officefileapi-404880-pdf-document-api-additional-content-manage-optional-content-group-visibility.md
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:
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;
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);
}
Imports DevExpress.Pdf
Imports System
Imports System.Linq
Imports DevExpress.Drawing
Using processor As 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.
Dim bitmap As DXBitmap = processor.CreateDXBitmap(1, 1000)
Dim pdfPrinterSettings As New PdfPrinterSettings()
processor.Print(pdfPrinterSettings)
End Using
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:
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 hides 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);
}
}
Imports DevExpress.Pdf
Imports System
Imports System.Linq
Imports DevExpress.Drawing
Shared Sub Main(ByVal args() As String)
Using processor As New PdfDocumentProcessor()
processor.LoadDocument("PdfLayers.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.
processor.DocumentFacade.OptionalContentVisibility.SetPrintState()
Dim bitmap As DXBitmap = processor.CreateDXBitmap(1, 1000)
Dim pdfPrinterSettings As New PdfPrinterSettings()
processor.Print(pdfPrinterSettings)
End Using
End Sub
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.