wpf-404952-controls-and-libraries-pdf-viewer-additional-content-layers.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 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 someone opens the document to view its content, or prints it, or exports it to an image.
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 layers settings and return to initial document state.
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:
<Grid>
<dxpdf:PdfViewerControl x:Name="pdfViewer" CommandBarStyle="Bars" ShowStartScreen="True"
DocumentSource="..\\PdfLayers.pdf"/>
</Grid>
using DevExpress.Pdf;
// ...
public partial class MainWindow : Window{
public MainWindow() {
InitializeComponent();
pdfViewer.DocumentLoaded += PdfViewer_DocumentLoaded;
}
private void PdfViewer_DocumentLoaded(object sender, RoutedEventArgs e) {
PdfDocumentFacade facade = pdfViewer.GetDocumentFacade();
facade.OptionalContentVisibility.Groups[0].Visible = false;
facade.OptionalContentVisibility.Groups[1].Visible = false;
facade.OptionalContentVisibility.Groups[2].Visible = true;
}
}
Imports DevExpress.Pdf
' ...
Partial Public Class MainWindow
Inherits Window
Public Sub New()
InitializeComponent()
AddHandler pdfViewer.DocumentLoaded, AddressOf PdfViewer_DocumentLoaded
End Sub
Private Sub PdfViewer_DocumentLoaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
Dim facade As PdfDocumentFacade = pdfViewer.GetDocumentFacade()
facade.OptionalContentVisibility.Groups(0).Visible = False
facade.OptionalContentVisibility.Groups(1).Visible = False
facade.OptionalContentVisibility.Groups(2).Visible = True
End Sub
End Class
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.
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:
ViewSettings applied to the layer in view state (when you view a document in a viewer).PrintSettings applied to the layer in print preview or when you print a document.ExportSettings applied to the layer when you export a document.ZoomSettings applied to the layer according to the zoom level.LanguageLanguage 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 hidden when you view the document, yet 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:
<Grid>
<dxpdf:PdfViewerControl x:Name="pdfViewer" CommandBarStyle="Bars" ShowStartScreen="True"
DocumentSource="..\\PdfLayers.pdf"/>
</Grid>
using DevExpress.Pdf;
// ...
public partial class MainWindow : Window{
public MainWindow() {
InitializeComponent();
pdfViewer.DocumentLoaded += PdfViewer_DocumentLoaded;
}
private void PdfViewer_DocumentLoaded(object sender, RoutedEventArgs e) {
PdfDocumentFacade facade = pdfViewer.GetDocumentFacade();
facade.OptionalContentVisibility.ActiveUsages = PdfOptionalContentUsageCategories.None;
pdfViewer.Print();
}
}
Imports DevExpress.Pdf
' ...
Partial Public Class MainWindow
Inherits Window
Public Sub New()
InitializeComponent()
AddHandler pdfViewer.DocumentLoaded, AddressOf PdfViewer_DocumentLoaded
End Sub
Private Sub PdfViewer_DocumentLoaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
Dim facade As PdfDocumentFacade = pdfViewer.GetDocumentFacade()
facade.OptionalContentVisibility.ActiveUsages = PdfOptionalContentUsageCategories.None
pdfViewer.Print()
End Sub
End Class
The following image illustrate the result: