VintaSoft Imaging .NET SDK 12.3: Documentation for .NET developer
In This Topic
    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 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:

    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:

    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:


    Manage the 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 an example 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);
        }
    }
    
    ''' <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:
    Here is an example 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();
        }
    }
    
    ''' <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