PDFForm Component

Properties   Methods   Events   Config Settings   Errors  

The PDFForm component offers PDF form management capabilities.

Syntax

nsoftware.SecurePDF.PDFForm

Remarks

The PDF specification defines seven interactive form field types:

• Button
• Check box
• Radio button
• Text box
• List box
• Combo box
• Signature

To begin, provide the input document as a file (InputFile), byte array (InputData), or stream (SetInputStream) and call the Open method. This method will populate the Fields collection with the existing form fields in the document. When finished editing the form, call the Close method to close the document and save the changes to either OutputFile, OutputData, or the stream set in SetOutputStream.

Adding and Modifying Form Fields

PDFForm includes three additional methods that allow you to customize the form field before it is created. The SetPage and SetPosition methods can be used to specify the form field's location (the page on which it will be added and its position on the page, respectively). If SetPage is not explicitly called, the field will be placed on the first page of the document by default. The SetFont method can also be used to configure font properties (name, size, style, and color) for form fields that contain text.

Button Fields

A button (also known as pushbutton) field is a button on the form that simply responds as soon as it is clicked. Because of this, it is the only form field that does not retain a permanent value. Use the AddButton method to add a button field:

C#
 Copy
int buttonIdx = form.AddButton("button", "Press Me");

The action associated with a button field can be updated to perform specific tasks, such as displaying an alert or triggering a script. The example below assigns a JavaScript action to display an alert message when the button is clicked.

C#
 Copy
form.Fields[buttonIdx].Action = "app.alert('Hello! This is a simple alert message.');";

Check Box Fields

A check box represents a form field that can be toggled between two states: on and off. Use the AddCheckBox method to add a check box field:

C#
 Copy
int checkBoxIdx = form.AddCheckBox("checkbox", false);

The value associated with a check box field determines whether it will be toggled on or off. The example below toggles the check box on.

C#
 Copy
form.Fields[checkBoxIdx].Value = "true";

Radio Button Fields

Radio button fields are a set of related buttons, each of which - just like check boxes - can be in one of two states: on or off. Radio buttons belong to a radio group in which at most one button in the group may be in the on state at a time. Use the AddRadioButton method to add a radio button field:

C#
 Copy
int radioButtonIdx = form.AddRadioButton("radioGroup", "radiobutton", false);
int radioButton2Idx = form.AddRadioButton("radioGroup", "radiobutton2", true);

A radio button field can be modified to change its state. The example below selects the first radio button, switching it on, which automatically deselects the other radio button in the same group, switching it off.

C#
 Copy
form.Fields[radioButtonIdx].Value = "true";

Text Box Fields

A text box field is box or space that allows the user to enter and edit text in a designated area on the form. It can contain default text and can also be configured as a password field to mask the input. Use the AddTextBox method to add a text box field:

C#
 Copy
int textBoxIdx = form.AddTextBox("textbox", "Enter your name here", false);

As shown in the example below, the value of a text box field can be modified to fill it with the desired text.

C#
 Copy
form.Fields[textBoxIdx].Value = "My name is John Doe";

List Box Fields

A list box field is a scrollable choice field that displays a list of selectable text items the user can choose from. Use the AddListBox method to add a list box field:

C#
 Copy
int listBoxIdx = form.AddListBox("numbers", "One\r\nTwo\r\nThree", "One");

A list box field can be modified to select one of the options. The example below updates the list box field to select the option "Three".

C#
 Copy
form.Fields[listBoxIdx].Value = "Three";

Combo Box Fields

A combo box field is a choice field that consists of a drop-down list of text items the user can choose from. At most one item may be selected at a time. Compared to list box fields, combo box fields include an editable text box that allows the user to enter a custom value in addition to the predefined options. Use the AddComboBox method to add a combo box field:

C#
 Copy
int comboBoxIdx = form.AddComboBox("colors", "Red\r\nGreen\r\nBlue", "Red");

A combo box field can be modified to select one of the options. The example below updates the combo box field to select the option "Blue".

C#
 Copy
form.Fields[comboBoxIdx].Value = "Blue";

Removing Form Fields

RemoveField removes a form field identified by its index, whereas RemoveFieldByName removes a field by using its name.

C#
 Copy
form.RemoveField(buttonIdx);
form.RemoveFieldByName("checkbox");

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

DecryptionCert Property (PDFForm Component)

The decryption certificate.

Syntax

• C#
• VB.NET

public Certificate DecryptionCert { get; set; }

Public Property DecryptionCert As Certificate

Remarks

This property is used to provide the certificate used for decryption. Note that this certificate must have a private key associated with it.

This property is not available at design time.

Fields Property (PDFForm Component)

The entire collection of form fields contained in the PDF document.

Syntax

• C#
• VB.NET

public PDFFieldList Fields { get; }

Public ReadOnly Property Fields As PDFFieldList

Remarks

This property is used to access individual form fields within the document.

The PDF specification allows for an advanced, tree-like structure of the form fields, with each field residing within that tree. Much like in the object-oriented approach, form fields inherit properties from the fields that are their immediate parents in the tree. The leaf fields, called "terminal" by the specification, are the actual fields available for filling in and submitting. The fields occupying intermediate tree nodes are abstract and are only there to define a set of their descendant fields.

The PDFForm component flattens the tree structure, presenting the fields as one linear list. The following mechanisms can be used to navigate the tree:

• Use the Terminal property to find out if the field is terminal/leaf and can be filled in.
• The FullName property contains the full name of the field in dotted format (parent.intermediate.child). Remove the last element from the name to obtain the name of the parent field (parent.intermediate in this case).
• Use the FindField method to easily locate the field in the Fields collection.

This property is read-only and not available at design time.

Font Property (PDFForm Component)

The currently set font.

Syntax

• C#
• VB.NET

public PDFFont Font { get; }

Public ReadOnly Property Font As PDFFont

Remarks

This property is used to access the font details specified using the SetFont method.

This property is read-only and not available at design time.

InputData Property (PDFForm Component)

A byte array containing the PDF document to process.

Syntax

• C#
• VB.NET

public byte[] InputData { get; set; }

Public Property InputData As Byte()

Remarks

This property is used to assign a byte array containing the PDF document to be processed.

This property is not available at design time.

InputFile Property (PDFForm Component)

The PDF file to process.

Syntax

• C#
• VB.NET

public string InputFile { get; set; }

Public Property InputFile As String

Default Value

""

Remarks

This property is used to provide a path to the PDF document to be processed.

OutputData Property (PDFForm Component)

A byte array containing the PDF document after processing.

Syntax

• C#
• VB.NET

public byte[] OutputData { get; }

Public ReadOnly Property OutputData As Byte()

Remarks

This property is used to read the byte array containing the produced output after the operation has completed. It will only be set if an output file and output stream have not been assigned via OutputFile and SetOutputStream respectively.

This property is read-only and not available at design time.

OutputFile Property (PDFForm Component)

The path to a local file where the output will be written.

Syntax

• C#
• VB.NET

public string OutputFile { get; set; }

Public Property OutputFile As String

Default Value

""

Remarks

This property is used to provide a path where the resulting PDF document will be saved after the operation has completed.

Overwrite Property (PDFForm Component)

Whether or not the component should overwrite files.

Syntax

• C#
• VB.NET

public bool Overwrite { get; set; }

Public Property Overwrite As Boolean

Default Value

False

Remarks

This property indicates whether or not the component will overwrite OutputFile, OutputData, or the stream set in SetOutputStream. If set to false, an error will be thrown whenever OutputFile, OutputData, or the stream set in SetOutputStream exists before an operation.

Password Property (PDFForm Component)

The password to decrypt the document with.

Syntax

• C#
• VB.NET

public string Password { get; set; }

Public Property Password As String

Default Value

""

Remarks

This property is used to provide the user password for decryption. Though it may be different from OwnerPassword, most implementations use the same value for both.

Position Property (PDFForm Component)

The currently set position.

Syntax

• C#
• VB.NET

public PDFPagePosition Position { get; }

Public ReadOnly Property Position As PDFPagePosition

Remarks

This property is used to access the position details specified using the SetPosition and SetPage methods.

This property is read-only and not available at design time.

AddBitmap Method (PDFForm Component)

Adds a bitmap image at the current position.

Syntax

• C#
• VB.NET

public void AddBitmap(string format, byte[] bitmapBytes, int bitmapWidth, int bitmapHeight, string width, string height);

Async Version
public async Task AddBitmap(string format, byte[] bitmapBytes, int bitmapWidth, int bitmapHeight, string width, string height);
public async Task AddBitmap(string format, byte[] bitmapBytes, int bitmapWidth, int bitmapHeight, string width, string height, CancellationToken cancellationToken);

Public Sub AddBitmap(ByVal Format As String, ByVal BitmapBytes As Byte(), ByVal BitmapWidth As Integer, ByVal BitmapHeight As Integer, ByVal Width As String, ByVal Height As String)

Async Version
Public Sub AddBitmap(ByVal Format As String, ByVal BitmapBytes As Byte(), ByVal BitmapWidth As Integer, ByVal BitmapHeight As Integer, ByVal Width As String, ByVal Height As String) As Task
Public Sub AddBitmap(ByVal Format As String, ByVal BitmapBytes As Byte(), ByVal BitmapWidth As Integer, ByVal BitmapHeight As Integer, ByVal Width As String, ByVal Height As String, cancellationToken As CancellationToken) As Task

Remarks

This function is not available in the current version of the product.

Use this function to add a bitmap image at the specified Position. Provide the parameters of the serialized image using the Format, BitmapBytes, BitmapWidth, and BitmapHeight parameters.

Use Width and Height parameters to specify the dimensions, in points, which the image should be scaled/stretched to when placed on the page.

Note: please make sure to provide the original width and height of the bitmap, in pixels, via the BitmapWidth and BitmapHeight parameters.

AddButton Method (PDFForm Component)

Adds a button field to the form.

Syntax

• C#
• VB.NET

public int AddButton(string name, string caption);

Async Version
public async Task<int> AddButton(string name, string caption);
public async Task<int> AddButton(string name, string caption, CancellationToken cancellationToken);

Public Function AddButton(ByVal Name As String, ByVal Caption As String) As Integer

Async Version
Public Function AddButton(ByVal Name As String, ByVal Caption As String) As Task(Of Integer)
Public Function AddButton(ByVal Name As String, ByVal Caption As String, cancellationToken As CancellationToken) As Task(Of Integer)

Remarks

This method is used to create a button field with name Name and caption Caption at the specified Position.

The button is added to the end of the Fields collection and can be modified using the properties of the respective PDFField object.

This method returns the index of the newly added field in the Fields collection.

AddCaption Method (PDFForm Component)

Adds a caption for a form field.

Syntax

• C#
• VB.NET

public void AddCaption(string caption);

Async Version
public async Task AddCaption(string caption);
public async Task AddCaption(string caption, CancellationToken cancellationToken);

Public Sub AddCaption(ByVal Caption As String)

Async Version
Public Sub AddCaption(ByVal Caption As String) As Task
Public Sub AddCaption(ByVal Caption As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to add a caption (title) for a form field at the specified Position.

AddCheckBox Method (PDFForm Component)

Adds a check box field to the form.

Syntax

• C#
• VB.NET

public int AddCheckBox(string name, bool defaultValue);

Async Version
public async Task<int> AddCheckBox(string name, bool defaultValue);
public async Task<int> AddCheckBox(string name, bool defaultValue, CancellationToken cancellationToken);

Public Function AddCheckBox(ByVal Name As String, ByVal DefaultValue As Boolean) As Integer

Async Version
Public Function AddCheckBox(ByVal Name As String, ByVal DefaultValue As Boolean) As Task(Of Integer)
Public Function AddCheckBox(ByVal Name As String, ByVal DefaultValue As Boolean, cancellationToken As CancellationToken) As Task(Of Integer)

Remarks

This method is used to create a check box field with name Name at the specified Position.

The DefaultValue parameter specifies the initial state of the check box (checked/unchecked).

The check box field is added to the end of the Fields collection and can be modified using the properties of the respective PDFField object.

This method returns the index of the newly added field in the Fields collection.

AddComboBox Method (PDFForm Component)

Adds a combo box field to the form.

Syntax

• C#
• VB.NET

public int AddComboBox(string name, string options, string defaultValue);

Async Version
public async Task<int> AddComboBox(string name, string options, string defaultValue);
public async Task<int> AddComboBox(string name, string options, string defaultValue, CancellationToken cancellationToken);

Public Function AddComboBox(ByVal Name As String, ByVal Options As String, ByVal DefaultValue As String) As Integer

Async Version
Public Function AddComboBox(ByVal Name As String, ByVal Options As String, ByVal DefaultValue As String) As Task(Of Integer)
Public Function AddComboBox(ByVal Name As String, ByVal Options As String, ByVal DefaultValue As String, cancellationToken As CancellationToken) As Task(Of Integer)

Remarks

This method is used to create a combo box field with name Name at the specified Position.

The Options parameter specifies a list of choices as a multi-line string.

The DefaultValue parameter specifies the initial value selected in the combo box.

The new combo box field is added to the end of the Fields collection and can be modified using the properties of the respective PDFField object.

This method returns the index of the newly added field in the Fields collection.

AddDrawing Method (PDFForm Component)

Adds a vector drawing at the current position.

Syntax

• C#
• VB.NET

public void AddDrawing(string format, byte[] drawingBytes, string width, string height);

Async Version
public async Task AddDrawing(string format, byte[] drawingBytes, string width, string height);
public async Task AddDrawing(string format, byte[] drawingBytes, string width, string height, CancellationToken cancellationToken);

Public Sub AddDrawing(ByVal Format As String, ByVal DrawingBytes As Byte(), ByVal Width As String, ByVal Height As String)

Async Version
Public Sub AddDrawing(ByVal Format As String, ByVal DrawingBytes As Byte(), ByVal Width As String, ByVal Height As String) As Task
Public Sub AddDrawing(ByVal Format As String, ByVal DrawingBytes As Byte(), ByVal Width As String, ByVal Height As String, cancellationToken As CancellationToken) As Task

Remarks

This function is not available in the current version of the product.

Use this function to add a vector drawing at the specified Position. Provide the drawing, as an encoded PDF appearance stream, via the DrawingBytes parameter.

Use Width and Height parameters to specify the dimensions, in points, which the drawing should be scaled/stretched to when placed on the page.

AddListBox Method (PDFForm Component)

Adds a list box field to the form.

Syntax

• C#
• VB.NET

public int AddListBox(string name, string options, string defaultValue);

Async Version
public async Task<int> AddListBox(string name, string options, string defaultValue);
public async Task<int> AddListBox(string name, string options, string defaultValue, CancellationToken cancellationToken);

Public Function AddListBox(ByVal Name As String, ByVal Options As String, ByVal DefaultValue As String) As Integer

Async Version
Public Function AddListBox(ByVal Name As String, ByVal Options As String, ByVal DefaultValue As String) As Task(Of Integer)
Public Function AddListBox(ByVal Name As String, ByVal Options As String, ByVal DefaultValue As String, cancellationToken As CancellationToken) As Task(Of Integer)

Remarks

This method is used to create a list box field with name Name at the specified Position.

The Options parameter specifies a list of choices as a multi-line string.

The DefaultValue parameter specifies the initial value selected in the list box.

The new list box field is added to the end of the Fields collection and can be modified using the properties of the respective PDFField object.

This method returns the index of the newly added field in the Fields collection.

AddNewPage Method (PDFForm Component)

Adds a new blank page to a PDF document.

Syntax

• C#
• VB.NET

public void AddNewPage(int pageIndex);

Async Version
public async Task AddNewPage(int pageIndex);
public async Task AddNewPage(int pageIndex, CancellationToken cancellationToken);

Public Sub AddNewPage(ByVal PageIndex As Integer)

Async Version
Public Sub AddNewPage(ByVal PageIndex As Integer) As Task
Public Sub AddNewPage(ByVal PageIndex As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to add a new page to the document at the position specified by the PageIndex parameter. Note that when this method returns, the Position will not be automatically moved to the newly added page.

AddRadioButton Method (PDFForm Component)

Adds a radio button to the form.

Syntax

• C#
• VB.NET

public int AddRadioButton(string radioGroup, string name, bool isDefaultButton);

Async Version
public async Task<int> AddRadioButton(string radioGroup, string name, bool isDefaultButton);
public async Task<int> AddRadioButton(string radioGroup, string name, bool isDefaultButton, CancellationToken cancellationToken);

Public Function AddRadioButton(ByVal RadioGroup As String, ByVal Name As String, ByVal IsDefaultButton As Boolean) As Integer

Async Version
Public Function AddRadioButton(ByVal RadioGroup As String, ByVal Name As String, ByVal IsDefaultButton As Boolean) As Task(Of Integer)
Public Function AddRadioButton(ByVal RadioGroup As String, ByVal Name As String, ByVal IsDefaultButton As Boolean, cancellationToken As CancellationToken) As Task(Of Integer)

Remarks

This method is used to create a radio button field with name Name, within the radio group RadioGroup, at the specified Position.

The IsDefaultButton parameter specifies whether the radio button will be selected initially (i.e., whether it will be the DefaultValue of the radio group).

The new radio button field is added to the end of the Fields collection and can be modified using the properties of the respective PDFField object.

This method returns the index of the newly added field in the Fields collection.

AddTextBox Method (PDFForm Component)

Adds a text box field to the form.

Syntax

• C#
• VB.NET

public int AddTextBox(string name, string defaultValue, bool password);

Async Version
public async Task<int> AddTextBox(string name, string defaultValue, bool password);
public async Task<int> AddTextBox(string name, string defaultValue, bool password, CancellationToken cancellationToken);

Public Function AddTextBox(ByVal Name As String, ByVal DefaultValue As String, ByVal Password As Boolean) As Integer

Async Version
Public Function AddTextBox(ByVal Name As String, ByVal DefaultValue As String, ByVal Password As Boolean) As Task(Of Integer)
Public Function AddTextBox(ByVal Name As String, ByVal DefaultValue As String, ByVal Password As Boolean, cancellationToken As CancellationToken) As Task(Of Integer)

Remarks

This method is used to create a text box field with name Name at the specified Position.

The DefaultValue parameter specifies the initial value contained in the text box.

The Password parameter specifies whether the text box is intended to contain a password. If this parameter is true, the text will be displayed as asterisk characters (*).

The new text box field is added to the end of the Fields collection and can be modified using the properties of the respective PDFField object.

This method returns the index of the newly added field in the Fields collection.

Close Method (PDFForm Component)

Closes an opened PDF document.

Syntax

• C#
• VB.NET

public void Close();

Async Version
public async Task Close();
public async Task Close(CancellationToken cancellationToken);

Public Sub Close()

Async Version
Public Sub Close() As Task
Public Sub Close(cancellationToken As CancellationToken) As Task

Remarks

This method is used to close the previously opened document specified in InputFile, InputData, or SetInputStream. It should always be preceded by a call to the Open method.

Example:

C#
 Copy
component.InputFile = "input.pdf";
component.Open();
// Some operation
component.Close();

If any changes are made to the document, they will be saved automatically to OutputFile, OutputData, or the stream set in SetOutputStream when this method is called. To configure this saving behavior, set the SaveChanges configuration setting.

Config Method (PDFForm Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CreateNew Method (PDFForm Component)

Creates a new document.

Syntax

• C#
• VB.NET

public void CreateNew();

Async Version
public async Task CreateNew();
public async Task CreateNew(CancellationToken cancellationToken);

Public Sub CreateNew()

Async Version
Public Sub CreateNew() As Task
Public Sub CreateNew(cancellationToken As CancellationToken) As Task

Remarks

Use this method to create a blank PDF document with one empty page.

Having created the baseline document, you can use methods of the component (such as AddStream) to add objects to it.

Encrypted Method (PDFForm Component)

Checks whether a PDF document is encrypted.

Syntax

• C#
• VB.NET

public bool Encrypted();

Async Version
public async Task<bool> Encrypted();
public async Task<bool> Encrypted(CancellationToken cancellationToken);

Public Function Encrypted() As Boolean

Async Version
Public Function Encrypted() As Task(Of Boolean)
Public Function Encrypted(cancellationToken As CancellationToken) As Task(Of Boolean)

Remarks

This method is used to determine whether or not the document specified in InputFile, InputData, or SetInputStream is encrypted. It will return false if the document is pseudo-encrypted with an empty password.

Example:

C#
 Copy
component.InputFile = "input.pdf";
if (component.Encrypted())
{
  // Set Password or DecryptionCert
}
component.Open();
// Some operation
component.Close();

FindField Method (PDFForm Component)

Locates a field in the document.

Syntax

• C#
• VB.NET

public int FindField(string name);

Async Version
public async Task<int> FindField(string name);
public async Task<int> FindField(string name, CancellationToken cancellationToken);

Public Function FindField(ByVal Name As String) As Integer

Async Version
Public Function FindField(ByVal Name As String) As Task(Of Integer)
Public Function FindField(ByVal Name As String, cancellationToken As CancellationToken) As Task(Of Integer)

Remarks

This method is used to quickly locate the field with name Name in the document. This method returns the index of the field in the Fields collection, or -1 if the field was not found.

Flatten Method (PDFForm Component)

Flattens the form by removing the interactive form fields.

Syntax

• C#
• VB.NET

public void Flatten();

Async Version
public async Task Flatten();
public async Task Flatten(CancellationToken cancellationToken);

Public Sub Flatten()

Async Version
Public Sub Flatten() As Task
Public Sub Flatten(cancellationToken As CancellationToken) As Task

Remarks

This method is used to substitute all the existing form fields in the document with their currently set values, thus fixing them.

This method strips the interactive form features from the document. The flattened fields are no longer fields and can no longer be modified or extracted. Any signatures that may have been included in the original document are removed from the flattened document.

GetFieldProperty Method (PDFForm Component)

Retrieves the value of a field property.

Syntax

• C#
• VB.NET

public string GetFieldProperty(int fieldIndex, string fieldProperty);

Async Version
public async Task<string> GetFieldProperty(int fieldIndex, string fieldProperty);
public async Task<string> GetFieldProperty(int fieldIndex, string fieldProperty, CancellationToken cancellationToken);

Public Function GetFieldProperty(ByVal FieldIndex As Integer, ByVal FieldProperty As String) As String

Async Version
Public Function GetFieldProperty(ByVal FieldIndex As Integer, ByVal FieldProperty As String) As Task(Of String)
Public Function GetFieldProperty(ByVal FieldIndex As Integer, ByVal FieldProperty As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

This method is used to retrieve the value of a field property. Together with SetFieldProperty, this method provides an extensible way of managing the field settings that are not available through the PDFField type. The list of settings below may be extended in the future.

The FieldIndex parameter is the index of the field of interest in the Fields collection, and the FieldProperty parameter specifies the field property to read. The latter can take one of the following values:

Note: Each field property is only populated once the document has been loaded, which is reported by the DocumentInfo event.

GetPageProperty Method (PDFForm Component)

Retrieves the value of a page property.

Syntax

• C#
• VB.NET

public string GetPageProperty(int pageIndex, string pageProperty);

Async Version
public async Task<string> GetPageProperty(int pageIndex, string pageProperty);
public async Task<string> GetPageProperty(int pageIndex, string pageProperty, CancellationToken cancellationToken);

Public Function GetPageProperty(ByVal PageIndex As Integer, ByVal PageProperty As String) As String

Async Version
Public Function GetPageProperty(ByVal PageIndex As Integer, ByVal PageProperty As String) As Task(Of String)
Public Function GetPageProperty(ByVal PageIndex As Integer, ByVal PageProperty As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

This method is used to read general information about the pages of the document specified in InputFile, InputData, or SetInputStream, such as their dimensions and content positioning details.

The PageIndex parameter specifies the page to read information about (with a valid range from 0 to PageCount - 1), and the PageProperty parameter specifies the page property to read. The latter can take one of the following values:

Example:

C#
 Copy
int pageCount = 0;
component.OnDocumentInfo += (s, e) => { pageCount = e.PageCount; };
component.InputFile = "input.pdf";
component.Open();
for (int i = 0; i < pageCount; i++) component.GetPageProperty(i, "Height");
component.Close();

C#
 Copy
int x = int.Parse(pdfsign.GetPageProperty(0, "Width")) - 100;
int y = int.Parse(pdfsign.GetPageProperty(0, "Height")) - 100;
pdfsign.SetWidgetProperty("OffsetX", x.ToString());
pdfsign.SetWidgetProperty("OffsetY", y.ToString());

NOTE: If the document is not already opened, this method will open it, perform the operation, then close it.

Open Method (PDFForm Component)

Opens a PDF document for processing.

Syntax

• C#
• VB.NET

public void Open();

Async Version
public async Task Open();
public async Task Open(CancellationToken cancellationToken);

Public Sub Open()

Async Version
Public Sub Open() As Task
Public Sub Open(cancellationToken As CancellationToken) As Task

Remarks

This method is used to open the document specified in InputFile, InputData, or SetInputStream before performing some operation on it, such as adding, editing, or removing form fields. When finished, call Close to complete or discard the operation.

It is recommended to use this method (alongside Close) when performing multiple operations on the document at once.

NOTE: This method will populate the Fields collection with any form fields found in the document.

RemoveField Method (PDFForm Component)

Removes a field from the document.

Syntax

• C#
• VB.NET

public void RemoveField(int index);

Async Version
public async Task RemoveField(int index);
public async Task RemoveField(int index, CancellationToken cancellationToken);

Public Sub RemoveField(ByVal Index As Integer)

Async Version
Public Sub RemoveField(ByVal Index As Integer) As Task
Public Sub RemoveField(ByVal Index As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to remove a field from the document. The Index parameter specifies the index of the field in the Fields collection to be removed.

NOTE: This method can only be used with terminal fields.

RemoveFieldByName Method (PDFForm Component)

Removes a field from the document.

Syntax

• C#
• VB.NET

public void RemoveFieldByName(string name);

Async Version
public async Task RemoveFieldByName(string name);
public async Task RemoveFieldByName(string name, CancellationToken cancellationToken);

Public Sub RemoveFieldByName(ByVal Name As String)

Async Version
Public Sub RemoveFieldByName(ByVal Name As String) As Task
Public Sub RemoveFieldByName(ByVal Name As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to remove a field from the document. The Name parameter specifies the full name of the field in the Fields collection to be removed.

NOTE: This method can only be used with terminal fields.

Reset Method (PDFForm Component)

Resets the component.

Syntax

• C#
• VB.NET

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

This method is used to reset the component's properties and configuration settings to their default values.

SetFieldProperty Method (PDFForm Component)

Sets the value of a field property.

Syntax

• C#
• VB.NET

public void SetFieldProperty(int fieldIndex, string fieldProperty, string value);

Async Version
public async Task SetFieldProperty(int fieldIndex, string fieldProperty, string value);
public async Task SetFieldProperty(int fieldIndex, string fieldProperty, string value, CancellationToken cancellationToken);

Public Sub SetFieldProperty(ByVal FieldIndex As Integer, ByVal FieldProperty As String, ByVal Value As String)

Async Version
Public Sub SetFieldProperty(ByVal FieldIndex As Integer, ByVal FieldProperty As String, ByVal Value As String) As Task
Public Sub SetFieldProperty(ByVal FieldIndex As Integer, ByVal FieldProperty As String, ByVal Value As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to modify the value of a field property. Together with GetFieldProperty, this method provides an extensible way of managing the field settings that are not available through the PDFField type. The list of settings below may be extended in the future.

The FieldIndex parameter is the index of the field of interest in the Fields collection, and the FieldProperty and Value parameters specify the field property and value to set respectively. The former can take one of the following values:

SetFont Method (PDFForm Component)

Sets the font properties to be applied to form fields.

Syntax

• C#
• VB.NET

public void SetFont(string name, string size, string style, string color);

Async Version
public async Task SetFont(string name, string size, string style, string color);
public async Task SetFont(string name, string size, string style, string color, CancellationToken cancellationToken);

Public Sub SetFont(ByVal Name As String, ByVal Size As String, ByVal Style As String, ByVal Color As String)

Async Version
Public Sub SetFont(ByVal Name As String, ByVal Size As String, ByVal Style As String, ByVal Color As String) As Task
Public Sub SetFont(ByVal Name As String, ByVal Size As String, ByVal Style As String, ByVal Color As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to define the font attributes for text in form fields.

The Name parameter specifies the font name.

The Size parameter specifies the font size, either as an absolute value (e.g., "12") or relative adjustment (e.g., "+2").

The Style parameter specifies the font style: a combination of bold ("B"), italic ("I"), or underline ("U").

The Color parameter specifies the font color in hexadecimal format.

SetInputStream Method (PDFForm Component)

Sets the stream containing the PDF document to process.

Syntax

• C#
• VB.NET

public void SetInputStream(System.IO.Stream inputStream);

Async Version
public async Task SetInputStream(System.IO.Stream inputStream);
public async Task SetInputStream(System.IO.Stream inputStream, CancellationToken cancellationToken);

Public Sub SetInputStream(ByVal InputStream As System.IO.Stream)

Async Version
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream) As Task
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method is used to set the stream from which the component will read the PDF document to be processed. If an input stream is set before the component attempts to perform operations on the document, the component will read the data from the input stream instead of from the InputFile or InputData properties.

NOTE: It may be useful to additionally set the CloseInputStreamAfterProcessing configuration setting to true when using input streams.

SetOutputStream Method (PDFForm Component)

Sets the stream to write the processed document to.

Syntax

• C#
• VB.NET

public void SetOutputStream(System.IO.Stream outputStream);

Async Version
public async Task SetOutputStream(System.IO.Stream outputStream);
public async Task SetOutputStream(System.IO.Stream outputStream, CancellationToken cancellationToken);

Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream)

Async Version
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream) As Task
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method is used to set the stream to which the component will write the resulting PDF document. If an output stream is set before the component attempts to perform operations on the document, the component will write the data to the output stream instead of writing to OutputFile or populating OutputData.

NOTE: It may be useful to additionally set the CloseOutputStreamAfterProcessing configuration setting to true when using output streams.

SetPage Method (PDFForm Component)

Sets the page to be used as the working page.

Syntax

• C#
• VB.NET

public void SetPage(int pageIndex);

Async Version
public async Task SetPage(int pageIndex);
public async Task SetPage(int pageIndex, CancellationToken cancellationToken);

Public Sub SetPage(ByVal PageIndex As Integer)

Async Version
Public Sub SetPage(ByVal PageIndex As Integer) As Task
Public Sub SetPage(ByVal PageIndex As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to specify the page on which all subsequent operations will be performed. The page is identified by the PageIndex parameter.

NOTE: PageIndex set to -1 specifies the last page of the document.

SetPosition Method (PDFForm Component)

Sets the position for form fields.

Syntax

• C#
• VB.NET

public void SetPosition(string X, string Y);

Async Version
public async Task SetPosition(string X, string Y);
public async Task SetPosition(string X, string Y, CancellationToken cancellationToken);

Public Sub SetPosition(ByVal X As String, ByVal Y As String)

Async Version
Public Sub SetPosition(ByVal X As String, ByVal Y As String) As Task
Public Sub SetPosition(ByVal X As String, ByVal Y As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to define the Position where form fields will be added. The X parameter specifies the horizontal position, and the Y parameter specifies the vertical position.

Values that are absolute, relative to the current position, and relative to the page dimensions are all supported.

Example:

C#
 Copy
// Sets to exact coordinates.
form.SetPosition("100", "20");
// Moves 20 points to the right and 20 points down from the current position.
form.SetPosition("{x}+20", "{y}-20");
// Moves 20 points from the right edge and 120 points from the top edge of the page.
form.SetPosition("{width}-20", "{height}-120");

DocumentInfo Event (PDFForm Component)

Fired when the document has been loaded into memory.

Syntax

• C#
• VB.NET

public event OnDocumentInfoHandler OnDocumentInfo;

public delegate void OnDocumentInfoHandler(object sender, PDFFormDocumentInfoEventArgs e);

public class PDFFormDocumentInfoEventArgs : EventArgs {
  public int PageCount { get; }
  public int SignatureCount { get; }
}

Public Event OnDocumentInfo As OnDocumentInfoHandler

Public Delegate Sub OnDocumentInfoHandler(sender As Object, e As PDFFormDocumentInfoEventArgs)

Public Class PDFFormDocumentInfoEventArgs Inherits EventArgs
  Public ReadOnly Property PageCount As Integer
  Public ReadOnly Property SignatureCount As Integer
End Class

Remarks

This event is fired once per document processing routine to report that the document has been processed and loaded into memory.

The handler for this event is a good place to check the document structure and access document-related information such as page number and document file details. These may be useful when preparing the signature. For example, the GetPageProperty method can be used to find the optimal position for the signature widget.

The PageCount parameter reports the number of pages in the document.

The SignatureCount parameter reports the number of signatures in the document.

This event is fired when the Open method is called, but only after Password or RecipientInfo is fired (if applicable) and the document has been decrypted.

Error Event (PDFForm Component)

Fired when information is available about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, PDFFormErrorEventArgs e);

public class PDFFormErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As PDFFormErrorEventArgs)

Public Class PDFFormErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Log Event (PDFForm Component)

Fired once for each log message.

Syntax

• C#
• VB.NET

public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, PDFFormLogEventArgs e);

public class PDFFormLogEventArgs : EventArgs {
  public int LogLevel { get; }
  public string Message { get; }
  public string LogType { get; }
}

Public Event OnLog As OnLogHandler

Public Delegate Sub OnLogHandler(sender As Object, e As PDFFormLogEventArgs)

Public Class PDFFormLogEventArgs Inherits EventArgs
  Public ReadOnly Property LogLevel As Integer
  Public ReadOnly Property Message As String
  Public ReadOnly Property LogType As String
End Class

Remarks

This event is fired once for each log message generated by the component. The verbosity is controlled by the LogLevel configuration setting.

The LogLevel parameter indicates the detail level of the message. Possible values are:

The Message parameter is the log message.

The LogType parameter identifies the type of log entry. Possible values are:

• CertValidator
• Font
• HTTP
• PDFInvalidSignature
• PDFRevocationInfo
• Timestamp
• TSL

Password Event (PDFForm Component)

Fired when the component detects that the PDF document is encrypted with a password.

Syntax

• C#
• VB.NET

public event OnPasswordHandler OnPassword;

public delegate void OnPasswordHandler(object sender, PDFFormPasswordEventArgs e);

public class PDFFormPasswordEventArgs : EventArgs {
  public bool Available { get; }
  public bool Cancel { get; set; }
}

Public Event OnPassword As OnPasswordHandler

Public Delegate Sub OnPasswordHandler(sender As Object, e As PDFFormPasswordEventArgs)

Public Class PDFFormPasswordEventArgs Inherits EventArgs
  Public ReadOnly Property Available As Boolean
  Public Property Cancel As Boolean
End Class

Remarks

This event is fired during document processing to report that the document is encrypted with a password. It may be used to supply the correct decryption password to the Password property.

The Available parameter indicates whether the decryption password is already available to the component or still needs to be set. If this parameter is set to false, the correct password must be provided for the decryption attempt to succeed.

The Cancel parameter determines whether the component will stop firing this event to request a password.

RecipientInfo Event (PDFForm Component)

Fired for each recipient certificate of the encrypted PDF document.

Syntax

• C#
• VB.NET

public event OnRecipientInfoHandler OnRecipientInfo;

public delegate void OnRecipientInfoHandler(object sender, PDFFormRecipientInfoEventArgs e);

public class PDFFormRecipientInfoEventArgs : EventArgs {
  public string Issuer { get; }
  public string SerialNumber { get; }
  public string SubjectKeyIdentifier { get; }
  public bool Available { get; }
  public bool Cancel { get; set; }
}

Public Event OnRecipientInfo As OnRecipientInfoHandler

Public Delegate Sub OnRecipientInfoHandler(sender As Object, e As PDFFormRecipientInfoEventArgs)

Public Class PDFFormRecipientInfoEventArgs Inherits EventArgs
  Public ReadOnly Property Issuer As String
  Public ReadOnly Property SerialNumber As String
  Public ReadOnly Property SubjectKeyIdentifier As String
  Public ReadOnly Property Available As Boolean
  Public Property Cancel As Boolean
End Class

Remarks

This event is fired during document processing for each recipient certificate that the document has been encrypted for (if applicable). It may be used to identify the certificate(s) to load and supply to the DecryptionCert property.

The Issuer parameter specifies the subject of the issuer certificate.

The SerialNumber parameter specifies the serial number of the encryption certificate.

The SubjectKeyIdentifier parameter specifies the X.509 subjectKeyIdentifier extension value of the encryption certificate, encoded as a hex string.

The Available parameter indicates whether the decryption certificate is already available to the component or still needs to be set. If this parameter is set to false, the correct certificate must be provided for the decryption attempt to succeed.

The Cancel parameter determines whether the component will stop firing this event to request a certificate.

NOTE: The document may be encrypted with more than one certificate (or have "more than one recipient"), in which case each certificate will cause its own invocation of this event.

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

• EffectiveDate
• ExpirationDate
• ExtendedKeyUsage
• Fingerprint
• FingerprintSHA1
• FingerprintSHA256
• Issuer
• PrivateKey
• PrivateKeyAvailable
• PrivateKeyContainer
• PublicKey
• PublicKeyAlgorithm
• PublicKeyLength
• SerialNumber
• SignatureAlgorithm
• Store
• StorePassword
• StoreType
• SubjectAltNames
• ThumbprintMD5
• ThumbprintSHA1
• ThumbprintSHA256
• Usage
• UsageFlags
• Version
• Subject
• Encoded

Fields

C#
 Copy
certmgr.CertStoreType = CertStoreTypes.cstPKCS11;
certmgr.OnCertList += (s, e) => {
  secKeyBlob = e.CertEncoded;
};
certmgr.CertStore = @"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll";
certmgr.CertStorePassword = "123456"; //PIN
certmgr.ListStoreCertificates();

sftp.SSHCert = new Certificate(CertStoreTypes.cstPKCS11, secKeyBlob, "123456", "*");
sftp.SSHUser = "test";
sftp.SSHLogon("myhost", 22);

Constructors

• C#
• VB.NET

public Certificate();

Public Certificate()

• C#
• VB.NET

public Certificate(string certificateFile);

Public Certificate(ByVal CertificateFile As String)

• C#
• VB.NET

public Certificate(byte[] encoded);

Public Certificate(ByVal Encoded As Byte())

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, string store, string storePassword, string subject);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String)

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, string store, string storePassword, string subject, string configurationString);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, string store, string storePassword, byte[] encoded);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Encoded As Byte())

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, string subject);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Subject As String)

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, string subject, string configurationString);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, byte[] encoded);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Encoded As Byte())

PDFField Type

This type represents a single form field.

Remarks

PDFField objects provide access to the properties of an individual field object.

• Action
• AltName
• Caption
• DefaultValue
• FieldName
• FieldType
• FullName
• Height
• MaxLen
• OffsetX
• OffsetY
• Options
• PageIndex
• Terminal
• Value
• Visible
• Width

Fields

Constructors

• C#
• VB.NET

public PDFField();

Public PDFField()

PDFFont Type

The font used in a PDF document.

Remarks

This type contains details about the font being applied to form fields.

• Color
• Name
• Size
• Style

Fields

Constructors

• C#
• VB.NET

public PDFFont();

Public PDFFont()

PDFPagePosition Type

The position within a PDF document.

Remarks

This type contains information about the current position on a page.

• PageIndex
• X
• Y

Fields

Constructors

• C#
• VB.NET

public PDFPagePosition();

Public PDFPagePosition()

Config Settings (PDFForm Component)

PDFForm Config Settings

Base Config Settings

Trappable Errors (PDFForm Component)

PDFForm Errors

PDF Errors

Parsing Errors