PDFForm Module

Properties   Methods   Events   Config Settings   Errors  

The PDFForm module offers PDF form management capabilities.

Syntax

SecurePDF.PDFForm

Remarks

The PDF specification defines seven interactive form field types:

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

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

Adding and Modifying Form Fields

PDFForm includes three additional methods that allow you to customize the form field before it is created. SetPosition can be used to specify the form field's location (the page on which it is added and its position on the page). If SetPosition is not explicitly called, the field is placed on the first page of the document by default. SetFont 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: int buttonIdx = pdfform.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. pdfform.Fields[buttonIdx].Action = "app.alert('Hello! This is a simple alert message.');";

Checkbox Fields

A checkbox represents a form field that can be toggled between two states: on and off. Use the AddCheckBox method to add a checkbox field: int checkBoxIdx = pdfform.AddCheckBox("checkbox", false);

The value associated with a checkbox field determines whether it is toggled on or off. The example below toggles the checkbox on. pdfform.Fields[checkBoxIdx].Value = "true";

Radio Button Fields

Radio button fields are a set of related buttons, each of which - just like checkboxes - 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: int radioButtonIdx = pdfform.AddRadioButton("radiobutton", "radioGroup", false); int radioButton2Idx = pdfform.AddRadioButton("radiobutton2", "radioGroup", 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. pdfform.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: int textBoxIdx = pdfform.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. pdfform.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: int listBoxIdx = pdfform.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". pdfform.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: int comboBoxIdx = pdfform.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". pdfform.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. pdfform.RemoveField(buttonIdx); pdfform.RemoveFieldByName("checkbox");

Property List

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

Method List

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

Event List

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

Config Settings

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

DecryptionCert Property (PDFForm Module)

The decryption certificate.

Syntax

• Swift
• Objective-C

public var decryptionCert: Certificate {
  get {...}
  set {...}
}

@property (nonatomic,readonly,assign,getter=decryptionCertEffectiveDate) NSString* decryptionCertEffectiveDate;

- (NSString*)decryptionCertEffectiveDate;

@property (nonatomic,readonly,assign,getter=decryptionCertExpirationDate) NSString* decryptionCertExpirationDate;

- (NSString*)decryptionCertExpirationDate;

@property (nonatomic,readonly,assign,getter=decryptionCertExtendedKeyUsage) NSString* decryptionCertExtendedKeyUsage;

- (NSString*)decryptionCertExtendedKeyUsage;

@property (nonatomic,readonly,assign,getter=decryptionCertFingerprint) NSString* decryptionCertFingerprint;

- (NSString*)decryptionCertFingerprint;

@property (nonatomic,readonly,assign,getter=decryptionCertFingerprintSHA1) NSString* decryptionCertFingerprintSHA1;

- (NSString*)decryptionCertFingerprintSHA1;

@property (nonatomic,readonly,assign,getter=decryptionCertFingerprintSHA256) NSString* decryptionCertFingerprintSHA256;

- (NSString*)decryptionCertFingerprintSHA256;

@property (nonatomic,readonly,assign,getter=decryptionCertIssuer) NSString* decryptionCertIssuer;

- (NSString*)decryptionCertIssuer;

@property (nonatomic,readonly,assign,getter=decryptionCertPrivateKey) NSString* decryptionCertPrivateKey;

- (NSString*)decryptionCertPrivateKey;

@property (nonatomic,readonly,assign,getter=decryptionCertPrivateKeyAvailable) BOOL decryptionCertPrivateKeyAvailable;

- (BOOL)decryptionCertPrivateKeyAvailable;

@property (nonatomic,readonly,assign,getter=decryptionCertPrivateKeyContainer) NSString* decryptionCertPrivateKeyContainer;

- (NSString*)decryptionCertPrivateKeyContainer;

@property (nonatomic,readonly,assign,getter=decryptionCertPublicKey) NSString* decryptionCertPublicKey;

- (NSString*)decryptionCertPublicKey;

@property (nonatomic,readonly,assign,getter=decryptionCertPublicKeyAlgorithm) NSString* decryptionCertPublicKeyAlgorithm;

- (NSString*)decryptionCertPublicKeyAlgorithm;

@property (nonatomic,readonly,assign,getter=decryptionCertPublicKeyLength) int decryptionCertPublicKeyLength;

- (int)decryptionCertPublicKeyLength;

@property (nonatomic,readonly,assign,getter=decryptionCertSerialNumber) NSString* decryptionCertSerialNumber;

- (NSString*)decryptionCertSerialNumber;

@property (nonatomic,readonly,assign,getter=decryptionCertSignatureAlgorithm) NSString* decryptionCertSignatureAlgorithm;

- (NSString*)decryptionCertSignatureAlgorithm;

@property (nonatomic,readwrite,assign,getter=decryptionCertStore,setter=setDecryptionCertStore:) NSString* decryptionCertStore;

- (NSString*)decryptionCertStore;
- (void)setDecryptionCertStore :(NSString*)newDecryptionCertStore;

@property (nonatomic,readwrite,assign,getter=decryptionCertStoreB,setter=setDecryptionCertStoreB:) NSData* decryptionCertStoreB;

- (NSData*)decryptionCertStoreB;
- (void)setDecryptionCertStoreB :(NSData*)newDecryptionCertStore;

@property (nonatomic,readwrite,assign,getter=decryptionCertStorePassword,setter=setDecryptionCertStorePassword:) NSString* decryptionCertStorePassword;

- (NSString*)decryptionCertStorePassword;
- (void)setDecryptionCertStorePassword :(NSString*)newDecryptionCertStorePassword;

@property (nonatomic,readwrite,assign,getter=decryptionCertStoreType,setter=setDecryptionCertStoreType:) int decryptionCertStoreType;

- (int)decryptionCertStoreType;
- (void)setDecryptionCertStoreType :(int)newDecryptionCertStoreType;

@property (nonatomic,readonly,assign,getter=decryptionCertSubjectAltNames) NSString* decryptionCertSubjectAltNames;

- (NSString*)decryptionCertSubjectAltNames;

@property (nonatomic,readonly,assign,getter=decryptionCertThumbprintMD5) NSString* decryptionCertThumbprintMD5;

- (NSString*)decryptionCertThumbprintMD5;

@property (nonatomic,readonly,assign,getter=decryptionCertThumbprintSHA1) NSString* decryptionCertThumbprintSHA1;

- (NSString*)decryptionCertThumbprintSHA1;

@property (nonatomic,readonly,assign,getter=decryptionCertThumbprintSHA256) NSString* decryptionCertThumbprintSHA256;

- (NSString*)decryptionCertThumbprintSHA256;

@property (nonatomic,readonly,assign,getter=decryptionCertUsage) NSString* decryptionCertUsage;

- (NSString*)decryptionCertUsage;

@property (nonatomic,readonly,assign,getter=decryptionCertUsageFlags) int decryptionCertUsageFlags;

- (int)decryptionCertUsageFlags;

@property (nonatomic,readonly,assign,getter=decryptionCertVersion) NSString* decryptionCertVersion;

- (NSString*)decryptionCertVersion;

@property (nonatomic,readwrite,assign,getter=decryptionCertSubject,setter=setDecryptionCertSubject:) NSString* decryptionCertSubject;

- (NSString*)decryptionCertSubject;
- (void)setDecryptionCertSubject :(NSString*)newDecryptionCertSubject;

@property (nonatomic,readwrite,assign,getter=decryptionCertEncoded,setter=setDecryptionCertEncoded:) NSString* decryptionCertEncoded;

- (NSString*)decryptionCertEncoded;
- (void)setDecryptionCertEncoded :(NSString*)newDecryptionCertEncoded;

@property (nonatomic,readwrite,assign,getter=decryptionCertEncodedB,setter=setDecryptionCertEncodedB:) NSData* decryptionCertEncodedB;

- (NSData*)decryptionCertEncodedB;
- (void)setDecryptionCertEncodedB :(NSData*)newDecryptionCertEncoded;

Remarks

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

Fields Property (PDFForm Module)

The entire collection of form fields contained in the document.

Syntax

• Swift
• Objective-C

public var fields: Array<PDFField> {
  get {...}
}

@property (nonatomic,readonly,assign,getter=fieldCount) int fieldCount;

- (int)fieldCount;

- (NSString*)fieldAction:(int)fieldIndex;
- (void)setFieldAction:(int)fieldIndex :(NSString*)newFieldAction;

- (NSString*)fieldAltName:(int)fieldIndex;
- (void)setFieldAltName:(int)fieldIndex :(NSString*)newFieldAltName;

- (NSString*)fieldCaption:(int)fieldIndex;
- (void)setFieldCaption:(int)fieldIndex :(NSString*)newFieldCaption;

- (NSString*)fieldDefaultValue:(int)fieldIndex;
- (void)setFieldDefaultValue:(int)fieldIndex :(NSString*)newFieldDefaultValue;

- (NSString*)fieldName:(int)fieldIndex;
- (void)setFieldName:(int)fieldIndex :(NSString*)newFieldName;

- (int)fieldType:(int)fieldIndex;

- (NSString*)fieldFullName:(int)fieldIndex;

- (NSString*)fieldHeight:(int)fieldIndex;
- (void)setFieldHeight:(int)fieldIndex :(NSString*)newFieldHeight;

- (int)fieldMaxLen:(int)fieldIndex;
- (void)setFieldMaxLen:(int)fieldIndex :(int)newFieldMaxLen;

- (NSString*)fieldOffsetX:(int)fieldIndex;
- (void)setFieldOffsetX:(int)fieldIndex :(NSString*)newFieldOffsetX;

- (NSString*)fieldOffsetY:(int)fieldIndex;
- (void)setFieldOffsetY:(int)fieldIndex :(NSString*)newFieldOffsetY;

- (NSString*)fieldOptions:(int)fieldIndex;
- (void)setFieldOptions:(int)fieldIndex :(NSString*)newFieldOptions;

- (int)fieldPageIndex:(int)fieldIndex;

- (BOOL)fieldTerminal:(int)fieldIndex;

- (NSString*)fieldValue:(int)fieldIndex;
- (void)setFieldValue:(int)fieldIndex :(NSString*)newFieldValue;

- (BOOL)fieldVisible:(int)fieldIndex;
- (void)setFieldVisible:(int)fieldIndex :(BOOL)newFieldVisible;

- (NSString*)fieldWidth:(int)fieldIndex;
- (void)setFieldWidth:(int)fieldIndex :(NSString*)newFieldWidth;

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 module flattens the tree structure, presenting the fields as one linear list. The following mechanisms can be used to navigate the tree:

• Use Terminal to find out if the field is terminal/leaf and can be filled in.
• FullName 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 FindField to easily locate the field in the Fields collection.

This property is read-only.

Font Property (PDFForm Module)

The currently set font.

Syntax

• Swift
• Objective-C

public var font: PDFFont {
  get {...}
}

@property (nonatomic,readonly,assign,getter=fontColor) NSString* fontColor;

- (NSString*)fontColor;

@property (nonatomic,readonly,assign,getter=fontName) NSString* fontName;

- (NSString*)fontName;

@property (nonatomic,readonly,assign,getter=fontPath) NSString* fontPath;

- (NSString*)fontPath;

@property (nonatomic,readonly,assign,getter=fontSize) NSString* fontSize;

- (NSString*)fontSize;

@property (nonatomic,readonly,assign,getter=fontStyle) NSString* fontStyle;

- (NSString*)fontStyle;

Remarks

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

This property is read-only.

InputData Property (PDFForm Module)

A byte array containing the PDF document to process.

Syntax

• Swift
• Objective-C

public var inputData: Data {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=inputData,setter=setInputData:) NSData* inputData;

- (NSData*)inputData;
- (void)setInputData :(NSData*)newInputData;

Remarks

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

InputFile Property (PDFForm Module)

The PDF file to process.

Syntax

• Swift
• Objective-C

public var inputFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=inputFile,setter=setInputFile:) NSString* inputFile;

- (NSString*)inputFile;
- (void)setInputFile :(NSString*)newInputFile;

Default Value

""

Remarks

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

OutputData Property (PDFForm Module)

A byte array containing the PDF document after processing.

Syntax

• Swift
• Objective-C

public var outputData: Data {
  get {...}
}

@property (nonatomic,readonly,assign,getter=outputData) NSData* outputData;

- (NSData*)outputData;

Remarks

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

This property is read-only.

OutputFile Property (PDFForm Module)

The path to a local file where the output is written.

Syntax

• Swift
• Objective-C

public var outputFile: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=outputFile,setter=setOutputFile:) NSString* outputFile;

- (NSString*)outputFile;
- (void)setOutputFile :(NSString*)newOutputFile;

Default Value

""

Remarks

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

Overwrite Property (PDFForm Module)

Whether the module should overwrite files.

Syntax

• Swift
• Objective-C

public var overwrite: Bool {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=overwrite,setter=setOverwrite:) BOOL overwrite;

- (BOOL)overwrite;
- (void)setOverwrite :(BOOL)newOverwrite;

Default Value

False

Remarks

This property indicates whether the module overwrites OutputFile. If set to false, an error is thrown whenever OutputFile exists before an operation.

Password Property (PDFForm Module)

The password to decrypt the document with.

Syntax

• Swift
• Objective-C

public var password: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=password,setter=setPassword:) NSString* password;

- (NSString*)password;
- (void)setPassword :(NSString*)newPassword;

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.

PDFAConformanceLevel Property (PDFForm Module)

The PDF/A conformance level of the document.

Syntax

• Swift
• Objective-C

public var pdfaConformanceLevel: PDFFormPDFAConformanceLevels {
  get {...}
  set {...}
}

public enum PDFFormPDFAConformanceLevels: Int32 {
  case paclNone = 0
  case paclA1a = 1
  case paclA1b = 2
  case paclA2a = 3
  case paclA2b = 4
  case paclA2u = 5
  case paclA3a = 6
  case paclA3b = 7
  case paclA3u = 8
  case paclA4 = 9
  case paclA4e = 10
  case paclA4f = 11
}

@property (nonatomic,readwrite,assign,getter=PDFAConformanceLevel,setter=setPDFAConformanceLevel:) int PDFAConformanceLevel;

- (int)PDFAConformanceLevel;
- (void)setPDFAConformanceLevel :(int)newPDFAConformanceLevel;

Default Value

0

Remarks

This property is used to specify the desired PDF/A conformance level the module attempts to apply when operating on the document.

Possible values are:

Position Property (PDFForm Module)

The currently set position.

Syntax

• Swift
• Objective-C

public var position: PDFPagePosition {
  get {...}
}

@property (nonatomic,readonly,assign,getter=positionPageIndex) int positionPageIndex;

- (int)positionPageIndex;

@property (nonatomic,readonly,assign,getter=positionX) NSString* positionX;

- (NSString*)positionX;

@property (nonatomic,readonly,assign,getter=positionY) NSString* positionY;

- (NSString*)positionY;

Remarks

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

This property is read-only.

AddBitmap Method (PDFForm Module)

Adds a bitmap image to the document.

Syntax

• Swift
• Objective-C

public func addBitmap(format: String, bitmapBytes: Data, bitmapWidth: Int32, bitmapHeight: Int32, scaleX: String, scaleY: String) throws -> Void

- (void)addBitmap :(NSString*)format :(NSData*)bitmapBytes :(int)bitmapWidth :(int)bitmapHeight :(NSString*)scaleX :(NSString*)scaleY;

Remarks

This method is used to add a bitmap image to the document at the current Position.

Format and BitmapBytes specify the format and raw data of the serialized image respectively. Possible values for the former are:

• JPEG2000
• JPEG
• Custom

ScaleX and ScaleY specify the horizontal and vertical scaling of the bitmap as real values, with 1.0 being the actual size of the bitmap (100%).

AddButton Method (PDFForm Module)

Adds a button field to the form.

Syntax

• Swift
• Objective-C

public func addButton(fieldName: String, caption: String) throws -> Int32

- (int)addButton :(NSString*)fieldName :(NSString*)caption;

Remarks

This method is used to create a button field with name FieldName and caption Caption at the current 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 Module)

Adds a caption for a form field.

Syntax

• Swift
• Objective-C

public func addCaption(caption: String) throws -> Void

- (void)addCaption :(NSString*)caption;

Remarks

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

AddCheckBox Method (PDFForm Module)

Adds a checkbox field to the form.

Syntax

• Swift
• Objective-C

public func addCheckBox(fieldName: String, defaultValue: Bool) throws -> Int32

- (int)addCheckBox :(NSString*)fieldName :(BOOL)defaultValue;

Remarks

This method is used to create a checkbox field with name FieldName at the current Position.

DefaultValue specifies the initial state of the checkbox (checked/unchecked).

The checkbox 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 Module)

Adds a combo box field to the form.

Syntax

• Swift
• Objective-C

public func addComboBox(fieldName: String, options: String, defaultValue: String) throws -> Int32

- (int)addComboBox :(NSString*)fieldName :(NSString*)options :(NSString*)defaultValue;

Remarks

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

Options specifies a list of choices as a multi-line string. Each choice can either contain a user-readable value alone, or be followed by an internal (exported) name that is recorded as the value of the field if the option is selected. If provided, the internal name must be separated from the preceding user-readable value by the vertical bar character (|). If the internal name postfix is omitted, the user-readable value is recorded as the field value if the option is selected.

DefaultValue specifies the initial value selected in the combo box.

Example: pdfform.AddComboBox("topping", "Pepperoni\r\nPineapple\r\nSmoked Paprika|Paprika", ""); 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 Module)

Adds a vector drawing to the document.

Syntax

• Swift
• Objective-C

public func addDrawing(format: String, drawingBytes: Data, scaleX: String, scaleY: String) throws -> Void

- (void)addDrawing :(NSString*)format :(NSData*)drawingBytes :(NSString*)scaleX :(NSString*)scaleY;

Remarks

This method is used to add a vector drawing to the document at the current Position.

Format and DrawingBytes specify the format and raw data (as an encoded PDF appearance stream) of the drawing respectively. The former is reserved for future use.

ScaleX and ScaleY specify the horizontal and vertical scaling of the drawing as real values, with 1.0 being the actual size of the drawing (100%).

AddListBox Method (PDFForm Module)

Adds a list box field to the form.

Syntax

• Swift
• Objective-C

public func addListBox(fieldName: String, options: String, defaultValue: String) throws -> Int32

- (int)addListBox :(NSString*)fieldName :(NSString*)options :(NSString*)defaultValue;

Remarks

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

Options specifies a list of choices as a multi-line string. Each choice can either contain a user-readable value alone, or be followed by an internal (exported) name that is recorded as the value of the field if the option is selected. If provided, the internal name must be separated from the preceding user-readable value by the vertical bar character (|). If the internal name postfix is omitted, the user-readable value is recorded as the field value if the option is selected.

DefaultValue specifies the initial value selected in the list box.

Example: pdfform.AddListBox("topping", "Pepperoni\r\nPineapple\r\nSmoked Paprika|Paprika", ""); 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 Module)

Adds a new blank page to the document.

Syntax

• Swift
• Objective-C

public func addNewPage(pageIndex: Int32) throws -> Void

- (void)addNewPage :(int)pageIndex;

Remarks

This method is used to add a new page to the document at the position specified by PageIndex (zero-based). Use DefaultPageWidth and DefaultPageHeight to adjust the new page dimensions.

Note that upon completion of this method, the Position will not be automatically moved to the newly added page.

AddRadioButton Method (PDFForm Module)

Adds a radio button to the form.

Syntax

• Swift
• Objective-C

public func addRadioButton(fieldName: String, radioGroup: String, isDefaultButton: Bool) throws -> Int32

- (int)addRadioButton :(NSString*)fieldName :(NSString*)radioGroup :(BOOL)isDefaultButton;

Remarks

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

IsDefaultButton 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 Module)

Adds a text box field to the form.

Syntax

• Swift
• Objective-C

public func addTextBox(fieldName: String, defaultValue: String, password: Bool) throws -> Int32

- (int)addTextBox :(NSString*)fieldName :(NSString*)defaultValue :(BOOL)password;

Remarks

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

DefaultValue specifies the initial value contained in the text box.

Password specifies whether the text box is intended to contain a password. Pass true to have the text 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 Module)

Closes the opened document.

Syntax

• Swift
• Objective-C

public func close() throws -> Void

- (void)close;

Remarks

This method is used to close the previously opened document. It should always be preceded by a call to Open.

Example: component.InputFile = "input.pdf"; component.Open(); // Some operation component.Close(); If any changes are made to the document, they are saved automatically to OutputFile or OutputData when this method is called. To configure this saving behavior, set SaveChanges.

Config Method (PDFForm Module)

Sets or retrieves a configuration setting.

Syntax

• Swift
• Objective-C

public func config(configurationString: String) throws -> String

- (NSString*)config :(NSString*)configurationString;

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the module, 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 Module)

Creates a new PDF document.

Syntax

• Swift
• Objective-C

public func createNew() throws -> Void

- (void)createNew;

Remarks

This method is used to create a blank PDF document with one empty page. Use DefaultPageWidth and DefaultPageHeight to adjust the new page dimensions. Having created the baseline document, use the module's methods to add objects to it.

Encrypted Method (PDFForm Module)

Checks whether the document is encrypted.

Syntax

• Swift
• Objective-C

public func encrypted() throws -> Bool

- (BOOL)encrypted;

Remarks

This method is used to determine whether the document is encrypted. It returns false if the document is pseudo-encrypted with an empty password.

Example: component.InputFile = "input.pdf"; if (component.Encrypted()) { // Set Password or DecryptionCert } component.Open(); // Some operation component.Close(); NOTE: If the document is not already opened, this method opens it, performs the operation, then closes it.

FindField Method (PDFForm Module)

Locates a field in the document.

Syntax

• Swift
• Objective-C

public func findField(fieldName: String) throws -> Int32

- (int)findField :(NSString*)fieldName;

Remarks

This method is used to quickly locate the field with name FieldName 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 Module)

Flattens the form by removing the interactive form fields.

Syntax

• Swift
• Objective-C

public func flatten() throws -> Void

- (void)flatten;

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 Module)

Returns the value of a field property.

Syntax

• Swift
• Objective-C

public func getFieldProperty(fieldIndex: Int32, fieldProperty: String) throws -> String

- (NSString*)getFieldProperty :(int)fieldIndex :(NSString*)fieldProperty;

Remarks

This method is used to obtain 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.

FieldIndex is the index of the field of interest in the Fields collection, and FieldProperty specifies the field property to read. Possible values are:

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

GetPageProperty Method (PDFForm Module)

Returns the value of a page property.

Syntax

• Swift
• Objective-C

public func getPageProperty(pageIndex: Int32, pageProperty: String) throws -> String

- (NSString*)getPageProperty :(int)pageIndex :(NSString*)pageProperty;

Remarks

This method is used to obtain general information about the pages of the document, such as their dimensions and content positioning details.

PageIndex specifies the page to read information about (with a valid range from 0 to PageCount - 1), and PageProperty specifies the page property to read. Possible values are:

Example: 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(); The page properties can be used to adjust the position of the signature widget based on the page dimensions. For example: 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: Each page property is only populated once the document has been loaded, which is reported by the DocumentInfo event.

NOTE: If the document is not already opened, this method opens it, performs the operation, then closes it.

Open Method (PDFForm Module)

Opens the document for processing.

Syntax

• Swift
• Objective-C

public func open() throws -> Void

- (void)open;

Remarks

This method is used to open the document specified in InputFile or InputData 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 populates the Fields collection with any form fields found in the document.

RemoveField Method (PDFForm Module)

Removes a field from the document.

Syntax

• Swift
• Objective-C

public func removeField(index: Int32) throws -> Void

- (void)removeField :(int)index;

Remarks

This method is used to remove a field from the document. Index 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 Module)

Removes a field from the document.

Syntax

• Swift
• Objective-C

public func removeFieldByName(fieldName: String) throws -> Void

- (void)removeFieldByName :(NSString*)fieldName;

Remarks

This method is used to remove a field from the document. FieldName 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 Module)

Resets the module.

Syntax

• Swift
• Objective-C

public func reset() throws -> Void

- (void)reset;

Remarks

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

SetFieldProperty Method (PDFForm Module)

Sets the value of a field property.

Syntax

• Swift
• Objective-C

public func setFieldProperty(fieldIndex: Int32, fieldProperty: String, value: String) throws -> Void

- (void)setFieldProperty :(int)fieldIndex :(NSString*)fieldProperty :(NSString*)value;

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.

FieldIndex is the index of the field of interest in the Fields collection, and FieldProperty and Value specify the field property and value to set respectively. Possible values for the former are:

SetFont Method (PDFForm Module)

Sets the font properties to be applied to text.

Syntax

• Swift
• Objective-C

public func setFont(name: String, size: String, style: String, color: String) throws -> Void

- (void)setFont :(NSString*)name :(NSString*)size :(NSString*)style :(NSString*)color;

Remarks

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

Name specifies the font name. Full font names (e.g., Times New Roman, Arial Bold Italic), filenames (e.g., times.ttf, arialbi.ttf), and full file paths are all supported.

The list of system TrueType font names that are supported by the module can be obtained from SystemFontNames.

Use FontPaths to specify font search paths when passing a TrueType font without a full file path. Alternatively, pass the full path of the TrueType font file to Name.

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

Style specifies the font style. The following syntax is supported:

[B][I][bold][italic][##%][##%,##%][0.###][0.###]

For example:

• bold
• bold 50%
• bold italic 50%
• BI 50% 42%
• B 50% italic 0.42

Color specifies the font color in hash-prefixed hexadecimal format (such as #FF0000 for red). The following HTML color aliases are also supported:

SetPosition Method (PDFForm Module)

Sets the page and position for new form fields, text blocks, or images.

Syntax

• Swift
• Objective-C

public func setPosition(pageIndex: Int32, x: String, y: String) throws -> Void

- (void)setPosition :(int)pageIndex :(NSString*)X :(NSString*)Y;

Remarks

This method is used to define the Position where new form fields, text blocks, or images are added. The page is identified by PageIndex (zero-based), X specifies the horizontal position, and Y specifies the vertical position.

X and Y values that are absolute, relative to the current position, and relative to the page dimensions are all supported.

Example: // Sets to exact coordinates. pdfform.SetPosition(0, "100", "20"); // Moves 20 points to the right and 20 points down from the current position. pdfform.SetPosition(0, "{x}+20", "{y}-20"); // Moves 20 points from the right edge and 120 points from the top edge of the page. pdfform.SetPosition(0, "{width}-20", "{height}-120"); NOTE: PageIndex set to -1 specifies the last page of the document.

DocumentInfo Event (PDFForm Module)

Fired when the document has been loaded into memory.

Syntax

• Swift
• Objective-C

func onDocumentInfo(pageCount: Int32, signatureCount: Int32)

- (void)onDocumentInfo :(int)pageCount :(int)signatureCount;

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, GetPageProperty can be used to find the optimal position for the signature widget.

PageCount reports the number of pages in the document.

SignatureCount reports the number of signatures in the document.

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

Error Event (PDFForm Module)

Fired when information is available about errors during data delivery.

Syntax

• Swift
• Objective-C

func onError(errorCode: Int32, description: String)

- (void)onError :(int)errorCode :(NSString*)description;

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the module .

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.

FontLookup Event (PDFForm Module)

Fired when a required font is missing.

Syntax

• Swift
• Objective-C

func onFontLookup(fontName: String, fontPath: inout String)

- (void)onFontLookup :(NSString*)fontName :(NSString**)fontPath;

Remarks

This event is fired from within SetFont or Close to report that the font identified by FontName was not found in FontPaths. It may be used to provide substitute fonts on the fly as an extension to the FallbackFont configuration setting.

FontPath specifies the absolute path to the substitute font file. If empty, the substitute font defaults to FallbackFont, which can also be adjusted within the event handler for each missing font.

Example: component.OnFontLookup += (s, e) => { if (e.FontName == "Helvetica") { component.Config("FallbackFont=Arial"); } else { component.Config("FallbackFont=Times New Roman"); } };

Log Event (PDFForm Module)

Fired once for each log message.

Syntax

• Swift
• Objective-C

func onLog(logLevel: Int32, message: String, logType: String)

- (void)onLog :(int)logLevel :(NSString*)message :(NSString*)logType;

Remarks

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

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

Message is the log message.

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

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

Password Event (PDFForm Module)

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

Syntax

• Swift
• Objective-C

func onPassword(available: Bool, cancel: inout Bool)

- (void)onPassword :(BOOL)available :(int*)cancel;

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 Password.

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

Cancel determines whether the module will stop firing this event to request a password.

RecipientInfo Event (PDFForm Module)

Fired for each recipient certificate of the encrypted document.

Syntax

• Swift
• Objective-C

func onRecipientInfo(issuer: String, serialNumber: String, subjectKeyIdentifier: String, available: Bool, cancel: inout Bool)

- (void)onRecipientInfo :(NSString*)issuer :(NSString*)serialNumber :(NSString*)subjectKeyIdentifier :(BOOL)available :(int*)cancel;

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 DecryptionCert.

Issuer specifies the subject of the issuer certificate.

SerialNumber specifies the serial number of the encryption certificate.

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

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

Cancel determines whether the module 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 causes 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

Constructors

public init()

public init(encoded: Data)

public init(storeType: CertStoreTypes, store: String, storePassword: String, subject: String)

public init(storeType: CertStoreTypes, store: Data, storePassword: String, subject: String)

PDFField Type

A single form field.

Remarks

This type provides 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

public init()

PDFFont Type

The font used in the PDF document.

Remarks

This type contains details about the font being applied to text.

• Color
• Name
• Path
• Size
• Style

Fields

Constructors

public init()

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

public init()

Config Settings (PDFForm Module)

PDFForm Config Settings

Base Config Settings

Trappable Errors (PDFForm Module)

PDFForm Errors

PDF Errors

Parsing Errors