SetSignaturePosFromPlaceHolder(String) Method

In This Topic

Sets up the coordinates and dimensions of the signature's bounding box within the current page of the loaded PDF document. This is the location, where the signature is placed after the successful signing of the current document. This method uses an empty signature form field specified by its name, so called signature placeholder, previously added by GdPicturePDF.AddSignatureFormField method, to inherit its coordinates and dimensions. If you omit this method in the signing process, or the width or the height of a placeholder are set to 0, the signature will not be drawn, that means it becomes invisible on the current page.

Syntax

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

'Declaration
 
Public Overloads Function SetSignaturePosFromPlaceHolder( _
   ByVal SignatureName As String _
) As GdPictureStatus

public GdPictureStatus SetSignaturePosFromPlaceHolder( 
   string SignatureName
)

public function SetSignaturePosFromPlaceHolder( 
    SignatureName: String
): GdPictureStatus;

public function SetSignaturePosFromPlaceHolder( 
   SignatureName : String
) : GdPictureStatus;

public: GdPictureStatus SetSignaturePosFromPlaceHolder( 
   string* SignatureName
)

public:
GdPictureStatus SetSignaturePosFromPlaceHolder( 
   String^ SignatureName
)

Parameters

SignatureName: The name of the signature form field (placeholder). It is the FieldName parameter from the GdPicturePDF.AddSignatureFormField method or you can obtain this name using the GdPicturePDF.GetFormFieldTitle method.

Return Value

A member of the GdPictureStatus enumeration. If the method has been successfully followed, then the return value is GdPictureStatus.OK.

We strongly recommend always checking this status first.

Remarks

This method is only allowed for use with non-encrypted documents.

Just to remind you that if you want to apply the defined settings during the signing, you need to set up the required parameters before you start the signing process. But using this method in the whole process is optional.

This method can be used instead of the GdPicturePDF.SetSignaturePos method. A signature place holder can be created with the GdPicturePDF.AddSignatureFormField method.

This method requires the Digital Signatures component to run.

Example

How to set the signature's location on the current page using an empty signature form field. You can find the complete sample within the ApplySignature() method's example.

VB.NET
C#

Dim caption As String = "SetSignaturePosFromPlaceHolder"
Dim gdpicturePDF As GdPicturePDF = New GdPicturePDF()
            
'Please take a PDF document created in the example for the AddSignatureFormField() method.
Dim status As GdPictureStatus = gdpicturePDF.LoadFromFile("test_AddSignatureFormField.pdf", False)
If status <> GdPictureStatus.OK Then
    MessageBox.Show("The file can't be loaded.", caption)
    Goto [Error]
End If
            
'Please set the corresponding certificate - this is a mandatory step.
            
'Set the signature information. At least one parameter must be defined for the successful signing.
status = gdpicturePDF.SetSignatureInfo("Orpalis", "GdPicturePDF", "Toulouse (France)", "")
If status <> GdPictureStatus.OK Then
    MessageBox.Show("The method SetSignatureInfo() has failed with the status " + status.ToString(), caption)
    Goto [Error]
End If
            
'Find a placeholder for a signature.
Dim formID As Integer = 0
Dim formType As PdfFormFieldType = PdfFormFieldType.PdfFormFieldTypeUnknown
Dim signatureName As String = ""
'Here we demonstrate how to find out the signature's name (the name of the signature form field (placeholder)).
Dim formsCount As Integer = gdpicturePDF.GetFormFieldsCount()
status = gdpicturePDF.GetStat()
If gdpicturePDF.GetStat() = GdPictureStatus.OK Then
    If formsCount = 0 Then
        MessageBox.Show("This document does not include form fields.", caption)
        Goto [Error]
    End If
    'This step is strongly bound to the file "test_AddSignatureFormField.pdf".
    For i As Integer = 0 To formsCount - 1 - 1
        formID = gdpicturePDF.GetFormFieldId(i)
        status = gdpicturePDF.GetStat()
        If status = GdPictureStatus.OK Then
            formType = gdpicturePDF.GetFormFieldType(formID)
            status = gdpicturePDF.GetStat()
            If (status = GdPictureStatus.OK) AndAlso (formType = PdfFormFieldType.PdfFormFieldTypeSignature) Then
                signatureName = gdpicturePDF.GetFormFieldTitle(formID)
                status = gdpicturePDF.GetStat()
                'Only one signature form field is expected here - see the "test_AddSignatureFormField.pdf" file.
                Exit For
            End If
        End If
    Next
    If status <> GdPictureStatus.OK Then
        MessageBox.Show("Can't find a signature placeholder field. Status: " + status.ToString(), caption)
        Goto [Error]
    End If
Else
    MessageBox.Show("The method GetFormFieldsCount() has failed with the status " + status.ToString(), caption)
    Goto [Error]
End If
            
'Set the signature's location on the current page. This step is optional.
'If this step is omitted, the signature will be invisible.
status = gdpicturePDF.SetSignaturePosFromPlaceHolder(signatureName)
'If you know the form field's name, you can use it directly like this (see the file "test_AddSignatureFormField.pdf"):
'status = gdpicturePDF.SetSignaturePosFromPlaceHolder("Signature1")
If status <> GdPictureStatus.OK Then
    MessageBox.Show("The method SetSignaturePosFromPlaceHolder() has failed with the status: " + status.ToString(), caption)
    Goto [Error]
End If
            
'Please see the complete sample in the ApplySignature() method for next steps to follow.
            
[error]:
gdpicturePDF.Dispose()

string caption = "SetSignaturePosFromPlaceHolder";
GdPicturePDF gdpicturePDF = new GdPicturePDF();
            
//Please take a PDF document created in the example for the AddSignatureFormField() method.
GdPictureStatus status = gdpicturePDF.LoadFromFile("test_AddSignatureFormField.pdf", false);
if (status != GdPictureStatus.OK)
{
    MessageBox.Show("The file can't be loaded.", caption);
    goto error;
}
            
//Please set the corresponding certificate - this is a mandatory step.
            
//Set the signature information. At least one parameter must be defined for the successful signing.
status = gdpicturePDF.SetSignatureInfo("Orpalis", "GdPicturePDF", "Toulouse (France)", "");
if (status != GdPictureStatus.OK)
{
    MessageBox.Show("The method SetSignatureInfo() has failed with the status " + status.ToString(), caption);
    goto error;
}
            
//Find a placeholder for a signature.
int formID = 0;
PdfFormFieldType formType = PdfFormFieldType.PdfFormFieldTypeUnknown;
string signatureName = "";
//Here we demonstrate how to find out the signature's name (the name of the signature form field (placeholder)).
int formsCount = gdpicturePDF.GetFormFieldsCount();
status = gdpicturePDF.GetStat();
if (gdpicturePDF.GetStat() == GdPictureStatus.OK)
{
    if (formsCount == 0)
    {
        MessageBox.Show("This document does not include form fields.", caption);
        goto error;
    }
    //This step is strongly bound to the file "test_AddSignatureFormField.pdf".
    for (int i = 0; i < formsCount-1; i++ )
    {
        formID = gdpicturePDF.GetFormFieldId(i);
        status = gdpicturePDF.GetStat();
        if (status == GdPictureStatus.OK)
        {
            formType = gdpicturePDF.GetFormFieldType(formID);
            status = gdpicturePDF.GetStat();
            if ((status == GdPictureStatus.OK) &&
                (formType == PdfFormFieldType.PdfFormFieldTypeSignature))
            {
                signatureName = gdpicturePDF.GetFormFieldTitle(formID);
                status = gdpicturePDF.GetStat();
                //Only one signature form field is expected here - see the "test_AddSignatureFormField.pdf" file.
                break;
            }
        }
    }
    if (status != GdPictureStatus.OK)
    {
        MessageBox.Show("Can't find a signature placeholder field. Status: " + status.ToString(), caption);
        goto error;
    }
}
else
{
    MessageBox.Show("The method GetFormFieldsCount() has failed with the status " + status.ToString(), caption);
    goto error;
}
            
//Set the signature's location on the current page. This step is optional.
//If this step is omitted, the signature will be invisible.
status = gdpicturePDF.SetSignaturePosFromPlaceHolder(signatureName);
//If you know the form field's name, you can use it directly like this (see the file "test_AddSignatureFormField.pdf"):
//status = gdpicturePDF.SetSignaturePosFromPlaceHolder("Signature1");
if (status != GdPictureStatus.OK)
{
    MessageBox.Show("The method SetSignaturePosFromPlaceHolder() has failed with the status: " + status.ToString(), caption);
    goto error;
}
            
//Please see the complete sample in the ApplySignature() method for next steps to follow.
            
error:
gdpicturePDF.Dispose();

Reference

GdPicturePDF Class
GdPicturePDF Members
Overload List
SetSignaturePos Method
ApplySignature(String,PdfSignatureMode,Boolean) Method
GetSignatureCount Method
GetSignatureProperties Method
AddSignatureFormField Method
GetFormFieldTitle Method