NewOCG Method (GdPicturePDF)

Creates a new optional content group (OCG) entry, i.e. a layer, in the currently loaded PDF document.

Optional Content Groups, also knows as Layers, are a very effective tool to control the visibility of the page content, that can be selectively viewed or hidden, by users or viewers.

Please be aware that the newly created layer is not presented in any user interface since the GdPicturePDF class do not support this functionality yet.

Syntax

Visual Basic
C#
Delphi
JScript
Managed Extensions for C++
C++/CLI

'Declaration
 
Public Function NewOCG( _
   ByVal Title As String _
) As Integer

public int NewOCG( 
   string Title
)

public function NewOCG( 
    Title: String
): Integer;

public function NewOCG( 
   Title : String
) : int;

public: int NewOCG( 
   string* Title
)

public:
int NewOCG( 
   String^ Title
)

Parameters

Title: The title of the newly created optional content group.

Return Value

The unique identifier of the newly created OCG entry. Please always use the GetStat method to determine if this method has been successful.

Remarks

Please note that this method is only allowed for use with non-encrypted documents.

We strongly recommend using the GetStat method to identify the specific reason for the method's failure.

You also need to be aware that the newly created layer is not presented in any user interface since this functionality is not yet supported.

Example

How to create a new layer (OCG entry) with the image-based content in the PDF document.

VB.NET
C#

Dim caption As String = "Example: NewOCG"
Dim oGdPicturePDF As New GdPicturePDF()
If (oGdPicturePDF.NewPDF() = GdPictureStatus.OK) AndAlso
   (oGdPicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) = GdPictureStatus.OK) Then
    Dim image_res_name As String = oGdPicturePDF.AddJpegImageFromFile("image.jpg")
    Dim status As GdPictureStatus = oGdPicturePDF.GetStat()
    If status = GdPictureStatus.OK Then
        Dim ocgID As Integer = oGdPicturePDF.NewOCG("Image layer")
        status = oGdPicturePDF.GetStat()
        If (status = GdPictureStatus.OK) AndAlso
           (oGdPicturePDF.SetImageOptional(image_res_name, ocgID) = GdPictureStatus.OK) Then
            If (oGdPicturePDF.SetOCGExportState(ocgID, PdfOcgState.StateOff) = GdPictureStatus.OK) AndAlso
               (oGdPicturePDF.SetOCGLockedState(ocgID, True) = GdPictureStatus.OK) AndAlso
               (oGdPicturePDF.SetOCGPrintState(ocgID, PdfOcgState.StateOn) = GdPictureStatus.OK) AndAlso
               (oGdPicturePDF.SetOCGViewState(ocgID, PdfOcgState.StateOn) = GdPictureStatus.OK) AndAlso
               (oGdPicturePDF.SetOCGZoomMin(ocgID, 0) = GdPictureStatus.OK) AndAlso
               (oGdPicturePDF.SetOCGZoomMax(ocgID, 1) = GdPictureStatus.OK) Then
                If oGdPicturePDF.SaveToFile("test_NewOCG.pdf") = GdPictureStatus.OK Then
                    MessageBox.Show("The example HAS been followed successfully and the file has been saved.", caption)
                Else
                    MessageBox.Show("The example HAS been followed successfully, but the file can't be saved. Status: " + oGdPicturePDF.GetStat().ToString(), caption)
                End If
            Else
                MessageBox.Show("Setting up layer's options has failed with the status: " + oGdPicturePDF.GetStat().ToString(), caption)
            End If
        Else
            MessageBox.Show("The NewOCG() or SetImageOptional() method has failed with the status: " + oGdPicturePDF.GetStat().ToString(), caption)
        End If
    Else
        MessageBox.Show("The AddJpegImageFromFile() method has failed with the status: " + status.ToString(), caption)
    End If
Else
    MessageBox.Show("The document can't be created.", caption)
End If
oGdPicturePDF.Dispose()

string caption = "Example: NewOCG";
GdPicturePDF oGdPicturePDF = new GdPicturePDF();
if ((oGdPicturePDF.NewPDF() == GdPictureStatus.OK) &&
    (oGdPicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) == GdPictureStatus.OK))
{
    string image_res_name = oGdPicturePDF.AddJpegImageFromFile("image.jpg");
    GdPictureStatus status = oGdPicturePDF.GetStat();
    if (status == GdPictureStatus.OK)
    {
        int ocgID = oGdPicturePDF.NewOCG("Image layer");
        status = oGdPicturePDF.GetStat();
        if ((status == GdPictureStatus.OK) &&
            (oGdPicturePDF.SetImageOptional(image_res_name, ocgID) == GdPictureStatus.OK))
        {
            if ((oGdPicturePDF.SetOCGExportState(ocgID, PdfOcgState.StateOff) == GdPictureStatus.OK) &&
                (oGdPicturePDF.SetOCGLockedState(ocgID, true) == GdPictureStatus.OK) &&
                (oGdPicturePDF.SetOCGPrintState(ocgID, PdfOcgState.StateOn) == GdPictureStatus.OK) &&
                (oGdPicturePDF.SetOCGViewState(ocgID, PdfOcgState.StateOn) == GdPictureStatus.OK) &&
                (oGdPicturePDF.SetOCGZoomMin(ocgID, 0) == GdPictureStatus.OK) &&
                (oGdPicturePDF.SetOCGZoomMax(ocgID, 1) == GdPictureStatus.OK))
            {
                if (oGdPicturePDF.SaveToFile("test_NewOCG.pdf") == GdPictureStatus.OK)
                {
                    MessageBox.Show("The example HAS been followed successfully and the file has been saved.", caption);
                }
                else
                {
                    MessageBox.Show("The example HAS been followed successfully, but the file can't be saved. Status: " + oGdPicturePDF.GetStat().ToString(), caption);
                }
            }
            else
            {
                MessageBox.Show("Setting up layer's options has failed with the status: " + oGdPicturePDF.GetStat().ToString(), caption);
            }
        }
        else
        {
            MessageBox.Show("The NewOCG() or SetImageOptional() method has failed with the status: " + oGdPicturePDF.GetStat().ToString(), caption);
        }
    }
    else
    {
        MessageBox.Show("The AddJpegImageFromFile() method has failed with the status: " + status.ToString(), caption);
    }
}
else
{
    MessageBox.Show("The document can't be created.", caption);
}
oGdPicturePDF.Dispose();

Reference

GdPicturePDF Class
GdPicturePDF Members
GetOCGCount Method
GetOCG Method
DeleteOCG Method
SetImageOptional Method
SetFormFieldOptional Method
SetOCGTitle Method
BeginOCGMarkedContent Method
EndOCGMarkedContent Method