VintaSoft Imaging .NET SDK v8.7
In This Topic
    PDF: Working with optional content (layers) 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:
    ' The project, which uses this code, must have references to the following assemblies:
    ' - Vintasoft.Imaging
    ' - Vintasoft.Imaging.Pdf
    
    ''' <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
                  
    
    // The project, which uses this code, must have references to the following assemblies:
    // - Vintasoft.Imaging
    // - Vintasoft.Imaging.Pdf
    
    /// <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);
        }
    }
                    
    



    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:
    ' The project, which uses this code, must have references to the following assemblies:
    ' - Vintasoft.Imaging
    ' - Vintasoft.Imaging.Pdf
    
    ''' <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
                  
    
    // The project, which uses this code, must have references to the following assemblies:
    // - Vintasoft.Imaging
    // - Vintasoft.Imaging.Pdf
    
    /// <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();
        }
    }