NewOCG Method (GdPicturePDF)

Creates a new optional content group (OCG) entry, means 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.

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.

Example

How to create a new layer (OCG entry) with the image-based content in the PDF document. The layer in this example is best viewed (in some viewers it is only viewed) when zooming between 0% and 100%.

VB.NET
C#

Dim caption As String = "Example: NewOCG"
Dim oGdPicturePDF As GdPicturePDF = New GdPicturePDF()
If (oGdPicturePDF.NewPDF() = GdPictureStatus.OK) AndAlso
   (oGdPicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) = GdPictureStatus.OK) Then
    'Creating content of a new layer.
    Dim image_res_name As String = oGdPicturePDF.AddJpegImageFromFile("image.jpg")
    If oGdPicturePDF.GetStat() = GdPictureStatus.OK Then
        Dim width As Single = oGdPicturePDF.GetPageWidth()
        Dim height As Single = oGdPicturePDF.GetPageHeight()
        'Drawing the layer's content on the current page.
        If oGdPicturePDF.DrawImage(image_res_name, 0, 0, width, height) = GdPictureStatus.OK Then
            'Creating the layer and setting its properties.
            Dim ocgID As Integer = oGdPicturePDF.NewOCG("Image layer")
            If (oGdPicturePDF.GetStat() = 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 DrawImage() method has failed with the status: " + oGdPicturePDF.GetStat().ToString(), caption)
        End If
    Else
        MessageBox.Show("The AddJpegImageFromFile() method has failed with the status: " + oGdPicturePDF.GetStat().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))
{
    //Creating content of a new layer.
    string image_res_name = oGdPicturePDF.AddJpegImageFromFile("image.jpg");
    if (oGdPicturePDF.GetStat() == GdPictureStatus.OK)
    {
        float width = oGdPicturePDF.GetPageWidth();
        float height = oGdPicturePDF.GetPageHeight();
        //Drawing the layer's content on the current page.
        if (oGdPicturePDF.DrawImage(image_res_name, 0, 0, width, height) == GdPictureStatus.OK)
        {
            //Creating the layer and setting its properties.
            int ocgID = oGdPicturePDF.NewOCG("Image layer");
            if ((oGdPicturePDF.GetStat() == 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 DrawImage() method has failed with the status: " + oGdPicturePDF.GetStat().ToString(), caption);
        }
    }
    else
    {
        MessageBox.Show("The AddJpegImageFromFile() method has failed with the status: " + oGdPicturePDF.GetStat().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