PDF: Optional content of PDF document

In This Topic

Optional content (PDF 1.5) refers to sections of content in a PDF document that can be selectively viewed or hidden by document authors or consumers. This capability is useful in items such as layered artwork, maps, multi-language documents and etc.

VintaSoft PDF .NET Plug-in allows to:

Manage the properties of optional content
Manage the properties of optional content group
Manage the visibility of optional content groups
Manage the rendering of optional content groups
Create new optional content group
Add some graphics to an optional content group.

Manage properties of optional content

Properties of optional content can be accessed using PdfDocument.OptionalContentProperties property, which value is an instance of PdfOptionalContentProperties class. PdfOptionalContentProperties class allows to:

get or sets a list of all optional content groups of PDF document using the PdfOptionalContentProperties.OptionalContentGroups property
get or set the default optional content configuration using the PdfOptionalContentProperties.DefaultConfiguration property
get a list of alternate optional content configurations using PdfOptionalContentProperties.Configurations property

An optional content group is a collection of graphics that can be made visible or invisible dynamically by users of viewer applications. The optional content group can be defined using the PdfOptionalContentGroup class. PdfOptionalContentGroup class allows to:

get or set a string suitable for presentation in a viewer application's user interface using the PdfOptionalContentGroup.Name property
get or set an intent that determines which optional content group's states to consider and ignore in calculating the visibility of content using the PdfOptionalContentGroup.Intent property

The configuration of optional content can be defined using the PdfOptionalContentConfiguration class and is used for managing the visibility of optional content groups. The PdfOptionalContentConfiguration class provides the following properties and methods:

PdfOptionalContentConfiguration.Name - string suitable for presentation in a user interface
PdfOptionalContentConfiguration.Intent - intent which determines which optional content groups states to consider and ignore in calculating the visibility of content
PdfOptionalContentConfiguration.PresentationOrder - the recommended order for presentation of optional content groups in a user interface. Any groups not listed in this array should not be presented in any user interface that uses the configuration
PdfOptionalContentConfiguration.OnGroups - list of optional content groups whose state should be set to ON when this configuration is applied
PdfOptionalContentConfiguration.OffGroups - list of optional content groups whose state should be set to OFF when this configuration is applied
PdfOptionalContentConfiguration.BaseState - a base state is used to initialize the states of all the optional content groups in a document when this configuration is applied
PdfOptionalContentConfiguration.GetGroupVisibility - returns the visibility of specified optional content group
PdfOptionalContentConfiguration.SetGroupVisibility - sets the visibility of specified optional content group

Manage rendering of optional content groups

The PdfDocument.OptionalContentProperties property allows to get/set the properties of document optional content. PdfOptionalContentProperties.DefaultConfiguration property allows to get/set the default configuration of optional content.

PdfOptionalContentProperties.Configurations property allows to get/set available configurations of optional content.

The PdfDocument.OptionalContentConfiguration property allows to get/set the current configuration of optional content. As the property value can be used only configuration from available configurations (PdfOptionalContentProperties.Configurations property).

Here is C#/VB.NET code that shows how to render a document with optional content:

/// <summary>
/// Renders a PDF document with optional content.
/// </summary>
/// <param name="pdfFilename">The PDF filename.</param>
public static void RenderPdfUsingOptonalContent(string pdfFilename)
{
    // get name of output PDF file
    string outputFileName = System.IO.Path.Combine(System.IO.Path.GetDirectoryName(pdfFilename), 
        System.IO.Path.GetFileNameWithoutExtension(pdfFilename));
    outputFileName = outputFileName + "_{0}_{1}.tif";

    // open document stream
    using (System.IO.Stream documentStream = 
        System.IO.File.Open(pdfFilename, System.IO.FileMode.Open))
    {
        // create image collection, which will store pages of PDF document
        using (Vintasoft.Imaging.ImageCollection documentImages = 
            new Vintasoft.Imaging.ImageCollection())
        {
            // add document pages to the image collection
            documentImages.Add(documentStream);

            // open PDF document
            Vintasoft.Imaging.Pdf.PdfDocument document = 
                Vintasoft.Imaging.Pdf.PdfDocumentController.OpenDocument(documentStream);

            // if document does not have optional content
            if (document.OptionalContentProperties == null)
            {
                System.Console.WriteLine("Document does not have optional content.");
                return;
            }

            // if PDF document has the default optional content configuration
            if (document.OptionalContentProperties.DefaultConfiguration != null)
            {
                // set the default optional content configuration as current optional content configuration
                document.OptionalContentConfiguration = document.OptionalContentProperties.DefaultConfiguration;
                // render PDF pages and save them to a multipage TIFF file
                SaveImages(documentImages, string.Format(outputFileName, "defaultConfig", document.OptionalContentConfiguration.Name));
            }

            // if PDF document has a list of optional content configurations
            if (document.OptionalContentProperties.Configurations != null)
            {
                // for each optional content configuration
                foreach (Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration config in
                    document.OptionalContentProperties.Configurations)
                {
                    // set the optional content configuration as current optional content configuration
                    document.OptionalContentConfiguration = config;
                    // render PDF pages and save them to a multipage TIFF file
                    SaveImages(documentImages, string.Format(outputFileName, "config", config.Name));
                }
            }


            // create custom optional content configuration
            Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration myConfig =
                new Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration(document, "MyConfig");
            // create an empty list of optional content groups whose state should
            // be set to ON when this configuration is applied
            myConfig.OnGroups =
                new Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentGroupList(document);
            // specify that optional content groups are "Off" by default
            myConfig.BaseState =
                Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfigurationBaseState.Off;
            // set custom optional content configuration as
            // current optional content configuration of PDF document
            document.OptionalContentConfiguration = myConfig;
            // for each optional content group of PDF document
            foreach (Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentGroup 
                group in document.OptionalContentProperties.OptionalContentGroups)
            {
                // clear list of "On" groups, i.e. specify that groups must be not visible
                myConfig.OnGroups.Clear();
                // add group to the list of "On" groups, i.e. specify that group must be visible
                myConfig.OnGroups.Add(group);
                // render PDF pages and save them to a file
                SaveImages(documentImages, string.Format(outputFileName, "group", group.Name));
            }


            // close PDF document
            Vintasoft.Imaging.Pdf.PdfDocumentController.CloseDocument(document);

            // free resources
            documentImages.ClearAndDisposeItems();
        }
    }
}

/// <summary>
/// Saves images (PDF pages) to the specified file.
/// </summary>
/// <param name="images">The image collection.</param>
/// <param name="filename">The filename where image collection must be saved.</param>
private static void SaveImages(Vintasoft.Imaging.ImageCollection images, string filename)
{
    // create encoder
    using (Vintasoft.Imaging.Codecs.Encoders.MultipageEncoderBase encoder = 
        Vintasoft.Imaging.Codecs.Encoders.AvailableEncoders.CreateMultipageEncoder(filename))
    {
        // set rendering settings
        images.SetRenderingSettings(new Vintasoft.Imaging.Codecs.Decoders.RenderingSettings(
            new Vintasoft.Imaging.Resolution(300, 300)));

        // specify that image collection should not be switched to new file
        encoder.SaveAndSwitchSource = false;
        // save images to a file
        images.SaveSync(filename, encoder);
    }
}

VB.NET

''' <summary>
''' Renders a PDF document with optional content.
''' </summary>
''' <param name="pdfFilename">The PDF filename.</param>
Public Shared Sub RenderPdfUsingOptonalContent(pdfFilename As String)
    ' get name of output PDF file
    Dim outputFileName As String = System.IO.Path.Combine(System.IO.Path.GetDirectoryName(pdfFilename), System.IO.Path.GetFileNameWithoutExtension(pdfFilename))
    outputFileName = outputFileName & "_{0}_{1}.tif"

    ' open document stream
    Using documentStream As System.IO.Stream = System.IO.File.Open(pdfFilename, System.IO.FileMode.Open)
        ' create image collection, which will store pages of PDF document
        Using documentImages As New Vintasoft.Imaging.ImageCollection()
            ' add document pages to the image collection
            documentImages.Add(documentStream)

            ' open PDF document
            Dim document As Vintasoft.Imaging.Pdf.PdfDocument = Vintasoft.Imaging.Pdf.PdfDocumentController.OpenDocument(documentStream)

            ' if document does not have optional content
            If document.OptionalContentProperties Is Nothing Then
                System.Console.WriteLine("Document does not have optional content.")
                Return
            End If

            ' if PDF document has the default optional content configuration
            If document.OptionalContentProperties.DefaultConfiguration IsNot Nothing Then
                ' set the default optional content configuration as current optional content configuration
                document.OptionalContentConfiguration = document.OptionalContentProperties.DefaultConfiguration
                ' render PDF pages and save them to a multipage TIFF file
                SaveImages(documentImages, String.Format(outputFileName, "defaultConfig", document.OptionalContentConfiguration.Name))
            End If

            ' if PDF document has a list of optional content configurations
            If document.OptionalContentProperties.Configurations IsNot Nothing Then
                ' for each optional content configuration
                For Each config As Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration In document.OptionalContentProperties.Configurations
                    ' set the optional content configuration as current optional content configuration
                    document.OptionalContentConfiguration = config
                    ' render PDF pages and save them to a multipage TIFF file
                    SaveImages(documentImages, String.Format(outputFileName, "config", config.Name))
                Next
            End If


            ' create custom optional content configuration
            Dim myConfig As New Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration(document, "MyConfig")
            ' create an empty list of optional content groups whose state should
            ' be set to ON when this configuration is applied
            myConfig.OnGroups = New Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentGroupList(document)
            ' specify that optional content groups are "Off" by default
            myConfig.BaseState = Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfigurationBaseState.Off
            ' set custom optional content configuration as
            ' current optional content configuration of PDF document
            document.OptionalContentConfiguration = myConfig
            ' for each optional content group of PDF document
            For Each group As Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentGroup In document.OptionalContentProperties.OptionalContentGroups
                ' clear list of "On" groups, i.e. specify that groups must be not visible
                myConfig.OnGroups.Clear()
                ' add group to the list of "On" groups, i.e. specify that group must be visible
                myConfig.OnGroups.Add(group)
                ' render PDF pages and save them to a file
                SaveImages(documentImages, String.Format(outputFileName, "group", group.Name))
            Next


            ' close PDF document
            Vintasoft.Imaging.Pdf.PdfDocumentController.CloseDocument(document)

            ' free resources
            documentImages.ClearAndDisposeItems()
        End Using
    End Using
End Sub

''' <summary>
''' Saves images (PDF pages) to the specified file.
''' </summary>
''' <param name="images">The image collection.</param>
''' <param name="filename">The filename where image collection must be saved.</param>
Private Shared Sub SaveImages(images As Vintasoft.Imaging.ImageCollection, filename As String)
    ' create encoder
    Using encoder As Vintasoft.Imaging.Codecs.Encoders.MultipageEncoderBase = Vintasoft.Imaging.Codecs.Encoders.AvailableEncoders.CreateMultipageEncoder(filename)
        ' set rendering settings
        images.SetRenderingSettings(New Vintasoft.Imaging.Codecs.Decoders.RenderingSettings(New Vintasoft.Imaging.Resolution(300, 300)))

        ' specify that image collection should not be switched to new file
        encoder.SaveAndSwitchSource = False
        ' save images to a file
        images.SaveSync(filename, encoder)
    End Using
End Sub

Create the optional content groups. Add some graphics to an optional content group

To create a group of optional content is necessary to create an instance of PdfOptionalContentGroup class and add it to the list of PdfOptionalContentProperties.OptionalContentGroups. If necessary, refresh the properties of content configuration.

To remove an existing group of optional content is necessary to remove the group from the list of PdfOptionalContentProperties.OptionalContentGroups. If necessary, refresh the properties of content configuration.

Graphics elements, which belong to the group of optional content, can be determined during the process of drawing graphics on PDF page. The PdfGraphics.BeginOptionalContent method must be called when block of optional content is started. The PdfGraphics.EndOptionalContent method must be called when block of optional content is finished.

Besides that the image-resource, form or annotation can be added to the group of optional content or exclude from it using OptionalContentGroup property:

PdfImageResource.OptionalContentGroup - the optional content group specifying the image visibility
PdfFormXObjectResource.OptionalContentGroup - the optional content group specifying the form visibility
PdfAnnotation.OptionalContentGroup - the optional content group specifying the annotation visibility

Here is C#/VB.NET code that shows how to create document with optional content:

/// <summary>
/// Creates PDF document with the optional content.
/// </summary>
/// <param name="pdfFilename">The PDF filename.</param>
public static void CreateDocumentWithOptionalContent(string pdfFilename)
{
    // create new PDF document
    using (Vintasoft.Imaging.Pdf.PdfDocument document = 
        new Vintasoft.Imaging.Pdf.PdfDocument(pdfFilename, Vintasoft.Imaging.Pdf.PdfFormat.Pdf_16))
    {
        // add empty page (A4 size)
        Vintasoft.Imaging.Pdf.Tree.PdfPage page = document.Pages.Add(
            Vintasoft.Imaging.PaperSizeKind.A4);

        // create two optional content groups
        Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentGroup layer1 =
            new Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentGroup(document, "Layer1");
        Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentGroup layer2 =
            new Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentGroup(document, "Layer2");

        // add optional content groups to OptionalContentProperties
        document.OptionalContentProperties =
            new Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentProperties(document);
        document.OptionalContentProperties.OptionalContentGroups.Add(layer1);
        document.OptionalContentProperties.OptionalContentGroups.Add(layer2);

        // get PdfGraphics for PDF page
        using (Vintasoft.Imaging.Pdf.Drawing.PdfGraphics g = page.GetGraphics())
        {
            Vintasoft.Imaging.Pdf.Tree.Fonts.PdfFont font = document.FontManager.GetStandardFont(
                Vintasoft.Imaging.Pdf.Tree.Fonts.PdfStandardFontType.TimesRoman);
            Vintasoft.Imaging.Pdf.Drawing.PdfBrush brush = new Vintasoft.Imaging.Pdf.Drawing.PdfBrush(
                System.Drawing.Color.Black);
            Vintasoft.Imaging.Pdf.Drawing.PdfBrush brush1 = new Vintasoft.Imaging.Pdf.Drawing.PdfBrush(
                System.Drawing.Color.Green);
            Vintasoft.Imaging.Pdf.Drawing.PdfBrush brush2 = new Vintasoft.Imaging.Pdf.Drawing.PdfBrush(
                System.Drawing.Color.Red);

            // draw not optional content
            g.DrawString("Not optional content", font, 20, brush, new System.Drawing.PointF(50, 650));

            // draw optional content "Layer1"
            g.BeginOptionalContent(layer1);
            g.DrawString(string.Format("Optional content '{0}'", layer1.Name),
                font, 25, brush1, new System.Drawing.PointF(50, 550));
            g.EndOptionalContent();

            // draw not optional content
            g.DrawString("Not optional content", font, 30, brush, new System.Drawing.PointF(50, 450));

            // draw optional content "Layer2"
            g.BeginOptionalContent(layer2);
            g.DrawString(string.Format("Optional content '{0}'", layer2.Name),
                font, 35, brush2, new System.Drawing.PointF(50, 350));
            g.EndOptionalContent();

            // draw not optional content
            g.DrawString("Not optional content", font, 40, brush, new System.Drawing.PointF(50, 250));
        }

        // create optional content configurations
        Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration configuration1 =
            new Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration(document, "Layer1 and Layer2");
        configuration1.SetGroupVisibility(layer1, true);
        configuration1.SetGroupVisibility(layer2, true);
        Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration configuration2 =
            new Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration(document, "Layer1");
        configuration2.SetGroupVisibility(layer1, true);
        configuration2.SetGroupVisibility(layer2, false);
        Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration configuration3 =
            new Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration(document, "Layer2");
        configuration3.SetGroupVisibility(layer1, false);
        configuration3.SetGroupVisibility(layer2, true);
        Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration configuration4 =
            new Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration(document, "No Layers");
        configuration4.SetGroupVisibility(layer1, false);
        configuration4.SetGroupVisibility(layer2, false);

        // create list of optional content configuration
        document.OptionalContentProperties.Configurations =
            new Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfigurationList(document);

        // add configurations to list
        document.OptionalContentProperties.Configurations.Add(configuration1);
        document.OptionalContentProperties.Configurations.Add(configuration2);
        document.OptionalContentProperties.Configurations.Add(configuration3);
        document.OptionalContentProperties.Configurations.Add(configuration4);

        // set default configuration
        document.OptionalContentProperties.DefaultConfiguration = configuration1;

        // set presentation order
        configuration1.PresentationOrder =
            new Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentPresentationOrder(document, layer1, layer2);

        // optional content panel is visible
        document.DocumentViewMode = Vintasoft.Imaging.Pdf.PdfDocumentViewMode.UseOC;

        // save changes in PDF document
        document.SaveChanges();
    }
}

VB.NET

''' <summary>
''' Creates PDF document with the optional content.
''' </summary>
''' <param name="pdfFilename">The PDF filename.</param>
Public Shared Sub CreateDocumentWithOptionalContent(pdfFilename As String)
    ' create new PDF document
    Using document As New Vintasoft.Imaging.Pdf.PdfDocument(pdfFilename, Vintasoft.Imaging.Pdf.PdfFormat.Pdf_16)
        ' add empty page (A4 size)
        Dim page As Vintasoft.Imaging.Pdf.Tree.PdfPage = document.Pages.Add(Vintasoft.Imaging.PaperSizeKind.A4)

        ' create two optional content groups
        Dim layer1 As New Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentGroup(document, "Layer1")
        Dim layer2 As New Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentGroup(document, "Layer2")

        ' add optional content groups to OptionalContentProperties
        document.OptionalContentProperties = New Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentProperties(document)
        document.OptionalContentProperties.OptionalContentGroups.Add(layer1)
        document.OptionalContentProperties.OptionalContentGroups.Add(layer2)

        ' get PdfGraphics for PDF page
        Using g As Vintasoft.Imaging.Pdf.Drawing.PdfGraphics = page.GetGraphics()
            Dim font As Vintasoft.Imaging.Pdf.Tree.Fonts.PdfFont = document.FontManager.GetStandardFont(Vintasoft.Imaging.Pdf.Tree.Fonts.PdfStandardFontType.TimesRoman)
            Dim brush As New Vintasoft.Imaging.Pdf.Drawing.PdfBrush(System.Drawing.Color.Black)
            Dim brush1 As New Vintasoft.Imaging.Pdf.Drawing.PdfBrush(System.Drawing.Color.Green)
            Dim brush2 As New Vintasoft.Imaging.Pdf.Drawing.PdfBrush(System.Drawing.Color.Red)

            ' draw not optional content
            g.DrawString("Not optional content", font, 20, brush, New System.Drawing.PointF(50, 650))

            ' draw optional content "Layer1"
            g.BeginOptionalContent(layer1)
            g.DrawString(String.Format("Optional content '{0}'", layer1.Name), font, 25, brush1, New System.Drawing.PointF(50, 550))
            g.EndOptionalContent()

            ' draw not optional content
            g.DrawString("Not optional content", font, 30, brush, New System.Drawing.PointF(50, 450))

            ' draw optional content "Layer2"
            g.BeginOptionalContent(layer2)
            g.DrawString(String.Format("Optional content '{0}'", layer2.Name), font, 35, brush2, New System.Drawing.PointF(50, 350))
            g.EndOptionalContent()

            ' draw not optional content
            g.DrawString("Not optional content", font, 40, brush, New System.Drawing.PointF(50, 250))
        End Using

        ' create optional content configurations
        Dim configuration1 As New Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration(document, "Layer1 and Layer2")
        configuration1.SetGroupVisibility(layer1, True)
        configuration1.SetGroupVisibility(layer2, True)
        Dim configuration2 As New Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration(document, "Layer1")
        configuration2.SetGroupVisibility(layer1, True)
        configuration2.SetGroupVisibility(layer2, False)
        Dim configuration3 As New Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration(document, "Layer2")
        configuration3.SetGroupVisibility(layer1, False)
        configuration3.SetGroupVisibility(layer2, True)
        Dim configuration4 As New Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfiguration(document, "No Layers")
        configuration4.SetGroupVisibility(layer1, False)
        configuration4.SetGroupVisibility(layer2, False)

        ' create list of optional content configuration
        document.OptionalContentProperties.Configurations = New Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentConfigurationList(document)

        ' add configurations to list
        document.OptionalContentProperties.Configurations.Add(configuration1)
        document.OptionalContentProperties.Configurations.Add(configuration2)
        document.OptionalContentProperties.Configurations.Add(configuration3)
        document.OptionalContentProperties.Configurations.Add(configuration4)

        ' set default configuration
        document.OptionalContentProperties.DefaultConfiguration = configuration1

        ' set presentation order
        configuration1.PresentationOrder = New Vintasoft.Imaging.Pdf.Tree.OptionalContent.PdfOptionalContentPresentationOrder(document, layer1, layer2)

        ' optional content panel is visible
        document.DocumentViewMode = Vintasoft.Imaging.Pdf.PdfDocumentViewMode.UseOC

        ' save changes in PDF document
        document.SaveChanges()
    End Using
End Sub

Send Feedback