PdfOptionalContentVisibility.ActiveUsages Property

Specifies which usage categories will be used to automatically manipulate the state of layers (optional content groups).

Namespace : DevExpress.Pdf

Assembly : DevExpress.Pdf.v25.2.Core.dll

NuGet Package : DevExpress.Pdf.Core

Declaration

C#
VB.NET

csharp

public PdfOptionalContentUsageCategories ActiveUsages { get; set; }

Public Property ActiveUsages As PdfOptionalContentUsageCategories

Property Value

Type	Description
PdfOptionalContentUsageCategories

An enumeration value that specifies usage category.

Available values:

Name	Description
None

Disables all settings automatically applied to layers.

| | View |

Enables settings automatically applied to the layer in view state (when you view a document in a viewer).

| | Print |

Enables settings automatically applied to the layer in print preview or when you print a document.

| | Export |

Enables settings automatically applied to the layer when you export a document.

| | Zoom |

Enables settings automatically applied to the layer according to the zoom level.

| | Language |

Enables language culture settings automatically applied to the layer.

| | All |

Enables all settings automatically applied to layers.

Remarks

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.

Use the ActiveUsages property to specify which settings from the default configuration should be preserved. For example, if you set ActiveUsages to PdfOptionalContentUsageCategories.Print, print settings from the default configuration are applied to layers when you print the document. Other default settings are disabled. Set ActiveUsages to none to disable all default settings and apply only those you specified in code.

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:

C#
VB.NET

csharp

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:

Refer to the following topic for more information on how to control layer visibility: Manage Visibility of Layers (Optional Content Groups).