Foxit PDF SDK
FSForm Class Reference
Inheritance diagram for FSForm:
FSBase

Instance Methods

(FSControl *) - addControl:field_name:field_type:rect:
 Add a new form control to a specified form field. If the form field does not exist, this function will add a form field as well. (Not support signature field)
More...
 
(BOOL) - exportToCSV:pdf_file_name:is_append:
 Export the form data to a CSV file.
More...
 
(BOOL) - exportToCSVWithStreamCallback:pdf_file_name:is_append:
 Export the form data to a CSV file.
More...
 
(BOOL) - exportToHTML:field_array:is_include:
 Export data of specified form fields to an HTML file.
More...
 
(BOOL) - exportToHTMLWithWriterCallback:field_array:is_include:
 Export data of specified form fields to an HTML file.
More...
 
(BOOL) - exportToTXT:field_array:is_include:
 Export data of specified form fields to a TXT file.
More...
 
(BOOL) - exportToTXTWithWriterCallback:field_array:is_include:
 Export data of specified form fields to a TXT file.
More...
 
(BOOL) - exportToXML:
 Export the form data to an XML file.
More...
 
(BOOL) - exportToXMLWithFieldArray:field_array:is_include:
 Export data of specified form fields to an XML file.
More...
 
(BOOL) - exportToXMLWithWriterCallback:field_array:is_include:
 Export data of specified form fields to an XML file.
More...
 
(void) - fixPageFields:
 Fix the fields which are in a PDF page but cannot be counted by current form object.
More...
 
(FSControl *) - getControl:index:
 Get a form control by index, in a specified PDF page.
More...
 
(FSControl *) - getControlAtDevicePoint:point:tolerance:type:matrix:
 Get the form control at a specified position, in device coordinate system.
More...
 
(FSControl *) - getControlAtPoint:point:tolerance:type:
 Get the form control at a specified position, in PDF coordinate system.
More...
 
(int) - getControlCount:
 Get count of form controls in a specified PDF page.
More...
 
(FSPDFDictionary *) - getDict
 Get the dictionary of current object.
More...
 
(FSPDFDoc *) - getDocument
 Get the PDF document, with which current form object is associated.
More...
 
(FSField *) - getField:filter:
 Get a form field by index, whose names satisfy the specified name filter.
More...
 
(int) - getFieldCount:
 Get the count of form fields, whose names satisfy the specified name filter.
More...
 
(FSFiller *) - getFormFiller
 Get the form filler.
More...
 
(BOOL) - importFromXML:
 Import the form data from an XML file.
More...
 
(id) - initWithDocument:
 Constructor, with PDF document.
More...
 
(id) - initWithOther:
 Constructor, with another form object.
More...
 
(BOOL) - isEmpty
 Check whether current object is empty or not.
More...
 
(BOOL) - moveControl:field_name:
 Move the control to a field specified by field name.
More...
 
(BOOL) - needConstructAppearances
 Check whether to construct appearance when loading form controls.
More...
 
(void) - removeControl:
 Remove a form control. (Not support to remove a form control from a signature field)
More...
 
(void) - removeField:
 Remove a form field. (Not support signature field)
More...
 
(BOOL) - renameField:new_field_name:
 Rename a field with a new name.
More...
 
(BOOL) - reset
 Reset data of all fields (except signature fields) to their default value.
More...
 
(void) - setConstructAppearances:
 Set a flag that specifies whether to construct appearances when loading form controls.
More...
 
(BOOL) - validateFieldName:field_name:
 Validate whether a field name can be used for a new field in specified field type.
More...
 

Properties

FSAlignment alignment
 Get or Set the alignment value which is used as document-wide default value.
More...
 
FSDefaultAppearancedefaultAppearance
 Get or Set the default appearance data.

 
FSFieldArrayfieldsInCalculationOrder
 Get or Set an array of form fields in calculation order.
More...
 

Detailed Description

An interactive form – sometimes referred to as an AcroForm – is a collection of fields for gathering information interactively from the user. A PDF document may contain any number of fields appearing on any combination of pages, all of which make up a single, global interactive form spanning the entire document. Arbitrary subsets of these fields can be imported or exported from the document.
Function pdf::PDFDoc::hasForm can be used to judge if a PDF document has interactive form.
A form object can be constructed form a specified PDF document. This class offers functions to retrieve form fields or form controls, import/export form data and other features. For example:

To import form data from a FDF/XFDF file or export such data to a FDF/XFDF file, please refer to functions pdf::PDFDoc::importFromFDF:types:page_range: and pdf::PDFDoc::exportToFDF:types:page_range:.
To fill the form, please construct a form filler object by current form object or retrieve the filler object by function Form::getFormFiller if such object has been constructed. (There should be only one form filler object for an interactive form).

See also
FSPDFDoc
FSFiller

Method Documentation

◆ addControl:field_name:field_type:rect:()

- (FSControl *) addControl: (FSPDFPage*)  page
field_name: (NSString *)  field_name
field_type: (FSFieldType field_type
rect: (FSRectF*)  rect 

Add a new form control to a specified form field. If the form field does not exist, this function will add a form field as well. (Not support signature field)

Application can use this function to add a new form control:

  • If the specified form field exists, a new form control will be created and set to the field.
  • If the specified form field does not exist, a new form field will be created according to parameter field_name and field_type and added to form, along with a newly created form control.

Whether a form field exists or not, it will be judged with input parameters field_name and field_type.
If user wants to add a new signature field, please use function pdf::PDFPage::addSignature: instead of current function.
The newly added form control has no appearance, so user should use setting methods in class Control or in related pdf field or widget annotation to set properties which will affect appearance. Some setting methods of class FSControl and FSField may directly update appearance, but functionannots::Annot::resetAppearanceStream of related widget annotation is still recommended to be called to ensure the appearance will indeed be updated.
For push button, check box, radio button, if user calls function annots::Annot::resetAppearanceStream directly without setting any properties, the default appearance style will be used:

  • push button: In related widget annotation, background color (in the MK dictionary) = 0xC0C0C0, highlighting mode = FSAnnotHighlightingPush.
  • check box/radio button: In related widget annotation, border width = 1.0, border style = FSBorderInfoSolid, background color (in the MK dictionary) = 0xFFFFFF, border color (in the MK dictionary) = 0xFFFFFF.


Parameters
[in]pageA valid PDF page, in which the new form control will be added. It should belong to the same PDF document as current form.
[in]field_nameField name. It should not be an empty string.
[in]field_typeField type. Please refer to values starting from FSFieldTypePushButton and this should be one of these values except FSFieldTypeSignature. If this is FSFieldTypeSignature, this function will throw exception FSErrUnsupported.
[in]rectRectangle of the new form control which specifies the position in PDF page. It should be in PDF coordinate system.
Returns
The newly added form control object.

◆ exportToCSV:pdf_file_name:is_append:()

- (BOOL) exportToCSV: (NSString *)  csv_file_path
pdf_file_name: (NSString *)  pdf_file_name
is_append: (BOOL)  is_append 

Export the form data to a CSV file.

Parameters
[in]csv_file_pathA full file path of a CSV file. This specifies the CSV file that form data will be exported to. This should not be an empty string.
[in]pdf_file_nameFile name of current PDF document. This file name will be written into the CSV file. This can be an empty string.
[in]is_appendA boolean value used to decide whether the form data is appended to the CSV file if the CSV file exists: YES means to append form data to an existed CSV file, while NO means not.
Returns
YES means success, while NO means failure.

◆ exportToCSVWithStreamCallback:pdf_file_name:is_append:()

- (BOOL) exportToCSVWithStreamCallback: (id<FSFileStreamCallback>)  csv_file
pdf_file_name: (NSString *)  pdf_file_name
is_append: (BOOL)  is_append 

Export the form data to a CSV file.

Parameters
[in]csv_fileA FSFileStreamCallback object which is implemented by user to save form data to a CSV file. This should not be nil. Please do not use append mode in writing callback functions.
[in]pdf_file_nameFile name of current PDF document. This file name will be written into the CSV file. This can be an empty string.
[in]is_appendA boolean value used to decide whether the form data is appended to the CSV file if the CSV file exists: YES means to append form data to an existed CSV file, while NO means not.
Returns
YES means success, while NO means failure.

◆ exportToHTML:field_array:is_include:()

- (BOOL) exportToHTML: (NSString *)  html_file_path
field_array: (FSFieldArray*)  field_array
is_include: (BOOL)  is_include 

Export data of specified form fields to an HTML file.

Parameters
[in]html_file_pathA full file path of an HTML file, to which data of specified form fields will be exported. This should not be an empty string.
[in]field_arrayAn array of form fields. Parameter is_include will decide whether data of these form fields are to exported or not. If this is an empty array, that means data of all form fields would be exported.
[in]is_includeA boolean value used to decide whether data of specified form fields are to be exported or not: YES means data of specified form fields are to be exported, while NO means data of specified form fields are not to be exported.
Returns
YES means success, while NO means failure.

◆ exportToHTMLWithWriterCallback:field_array:is_include:()

- (BOOL) exportToHTMLWithWriterCallback: (id<FSFileWriterCallback>)  html_file
field_array: (FSFieldArray*)  field_array
is_include: (BOOL)  is_include 

Export data of specified form fields to an HTML file.

Parameters
[in]html_fileA FSFileWriterCallback object which is implemented by user to save data of specified form fields to an HTML file. This should not be nil.
[in]field_arrayAn array of form fields. Parameter is_include will decide whether data of these form fields are to exported or not. If this is an empty array, that means data of all form fields would be exported.
[in]is_includeA boolean value used to decide whether data of specified form fields are to be exported or not: YES means data of specified form fields are to be exported, while NO means data of specified form fields are not to be exported.
Returns
YES means success, while NO means failure.

◆ exportToTXT:field_array:is_include:()

- (BOOL) exportToTXT: (NSString *)  txt_file_path
field_array: (FSFieldArray*)  field_array
is_include: (BOOL)  is_include 

Export data of specified form fields to a TXT file.

Parameters
[in]txt_file_pathA full file path of a TXT file, to which data of specified form fields will be exported. This should not be an empty string.
[in]field_arrayAn array of form fields. Parameter is_include will decide whether data of these form fields are to exported or not. If this is an empty array, that means data of all form fields would be exported.
[in]is_includeA boolean value used to decide whether data of specified form fields are to be exported or not: YES means data of specified form fields are to be exported, while NO means data of specified form fields are not to be exported.
Returns
YES means success, while NO means failure.

◆ exportToTXTWithWriterCallback:field_array:is_include:()

- (BOOL) exportToTXTWithWriterCallback: (id<FSFileWriterCallback>)  txt_file
field_array: (FSFieldArray*)  field_array
is_include: (BOOL)  is_include 

Export data of specified form fields to a TXT file.

Parameters
[in]txt_fileA FSFileWriterCallback object which is implemented by user to save data of specified form fields to a TXT file. This should not be nil.
[in]field_arrayAn array of form fields. Parameter is_include will decide whether data of these form fields are to exported or not. If this is an empty array, that means data of all form fields would be exported.
[in]is_includeA boolean value used to decide whether data of specified form fields are to be exported or not: YES means data of specified form fields are to be exported, while NO means data of specified form fields are not to be exported.
Returns
YES means success, while NO means failure.

◆ exportToXML:()

- (BOOL) exportToXML: (NSString *)  file_path

Export the form data to an XML file.

Parameters
[in]file_pathA full file_path of an XML file. This specifies the XML file that form data will be exported to.
Returns
YES means success, while NO means failure.

◆ exportToXMLWithFieldArray:field_array:is_include:()

- (BOOL) exportToXMLWithFieldArray: (NSString *)  file_path
field_array: (FSFieldArray*)  field_array
is_include: (BOOL)  is_include 

Export data of specified form fields to an XML file.

Parameters
[in]file_pathA full file_path of an XML file, to which data of specified form fields will be exported.
[in]field_arrayAn array of form fields. Parameter is_include will decide whether data of these form fields are to exported or not. If this is an empty array, that means data of all form fields would be exported.
[in]is_includeA boolean value used to decide whether data of specified form fields are to be exported or not: YES means data of specified form fields are to be exported, while NO means data of specified form fields are not to be exported.
Returns
YES means success, while NO means failure.

◆ exportToXMLWithWriterCallback:field_array:is_include:()

- (BOOL) exportToXMLWithWriterCallback: (id<FSFileWriterCallback>)  xml_file
field_array: (FSFieldArray*)  field_array
is_include: (BOOL)  is_include 

Export data of specified form fields to an XML file.

Parameters
[in]xml_fileA FSFileWriterCallback object which is implemented by user to save data of specified form fields to an XML file. This should not be nil.
[in]field_arrayAn array of form fields. Parameter is_include will decide whether data of these form fields are to exported or not. If this is an empty array, that means data of all form fields would be exported.
[in]is_includeA boolean value used to decide whether data of specified form fields are to be exported or not: YES means data of specified form fields are to be exported, while NO means data of specified form fields are not to be exported.
Returns
YES means success, while NO means failure.

◆ fixPageFields:()

- (void) fixPageFields: (int)  page_index

Fix the fields which are in a PDF page but cannot be counted by current form object.

It may cost much time if there are many fields in the specified page.

Parameters
[in]page_indexThe page index. Valid range: from 0 to (count-1). count is returned by function PDFDoc::getPageCount.
Returns
None.

◆ getControl:index:()

- (FSControl *) getControl: (FSPDFPage*)  page
index: (int)  index 

Get a form control by index, in a specified PDF page.

Parameters
[in]pageA valid PDF page object. It should belong to the same PDF document as current form.
[in]indexIndex of form control to be retrieved. Valid range: from 0 to (count-1). count is returned by function Field::getControlCount with same parameter page.
Returns
A form control object.

◆ getControlAtDevicePoint:point:tolerance:type:matrix:()

- (FSControl *) getControlAtDevicePoint: (FSPDFPage*)  page
point: (FSPointF*)  point
tolerance: (float)  tolerance
type: (FSFieldType type
matrix: (FSMatrix2D*)  matrix 

Get the form control at a specified position, in device coordinate system.

Parameters
[in]pageA valid PDF page object. It should be in the same document as current form.
[in]pointA position, in device coordinate system.
[in]toleranceTolerance value. Valid range: 0.0f to 30.0f.
[in]typeThe field type whose form control will be retrieved. Please refer to values starting from FSFieldTypeUnknown and this should be one of these values. FSFieldTypeUnknown means not to care about the field type and just to retrieve the first form control at the specified position.
[in]matrixA transformation matrix. Usually this is returned by function pdf::PDFPage::getDisplayMatrix:top:width:height:rotate:. If this is nil, current function will have the same feature as function Form::getControlAtPoint:point:tolerance:type:.
Returns
A form control object. If the return value of function Control::isEmpty for the returned form control object is YES, that means no suitable form control is around the specified position.

◆ getControlAtPoint:point:tolerance:type:()

- (FSControl *) getControlAtPoint: (FSPDFPage*)  page
point: (FSPointF*)  point
tolerance: (float)  tolerance
type: (FSFieldType type 

Get the form control at a specified position, in PDF coordinate system.

Parameters
[in]pageA valid PDF page object. It should be in the same document as current form.
[in]pointA position, in PDF coordinate system.
[in]toleranceTolerance value. Valid range: 0.0f to 30.0f.
[in]typeThe field type whose form control will be retrieved. Please refer to values starting from FSFieldTypeUnknown and this should be one of these values. FSFieldTypeUnknown means not to care about the field type and just to retrieve the first form control at the specified position.
Returns
A form control object. If the return value of function Control::isEmpty for the returned form control object is YES, that means no suitable form control is around the specified position.

◆ getControlCount:()

- (int) getControlCount: (FSPDFPage*)  page

Get count of form controls in a specified PDF page.

Parameters
[in]pageA valid PDF page object. It should belong to the same PDF document as current form.
Returns
The count of the form controls in the specified PDF page.

◆ getDict()

- (FSPDFDictionary *) getDict

Get the dictionary of current object.

Returns
The dictionary of current object. If there is any error, this function will return nil.

◆ getDocument()

- (FSPDFDoc *) getDocument

Get the PDF document, with which current form object is associated.

Returns
A PDF document object.

◆ getField:filter:()

- (FSField *) getField: (int)  index
filter: (NSString *)  filter 

Get a form field by index, whose names satisfy the specified name filter.

Parameters
[in]indexIndex of form field to be retrieved. Valid range: from 0 to (count-1). count is returned by function Form::getFieldCount: with same parameter filter.
[in]filterA filter string. If this is an empty string, that means to count all form fields; if this is valid, that means to count those form fields whose names are partially matched parameter filter. For example, if parameter filter is "text1", the filter will match text1.0, text1.2.0, etc; but not match test10 or test11.1.

Returns
A form field object.

◆ getFieldCount:()

- (int) getFieldCount: (NSString *)  filter

Get the count of form fields, whose names satisfy the specified name filter.

Parameters
[in]filterA filter string. If this is an empty string, that means to count all form fields; if this is valid, that means to count those form fields whose names are partially matched parameter filter. For example, if parameter filter is "text1", the filter will match text1.0, text1.2.0, etc; but not match test10 or test11.1.

Returns
The count of the form fields with specified name filter.

◆ getFormFiller()

- (FSFiller *) getFormFiller

Get the form filler.

Returns
The filler object. If the return value of function Filler::isEmpty for the returned filler object is YES, that means form filler has not been constructed yet. For this case, please construct a filler with current form.

◆ importFromXML:()

- (BOOL) importFromXML: (NSString *)  file_path

Import the form data from an XML file.

Parameters
[in]file_pathA full file_path of an existing XML file. This specifies the XML file that form data will be imported from.
Returns
YES means success, while NO means failure.

◆ initWithDocument:()

- (id) initWithDocument: (FSPDFDoc*)  document

Constructor, with PDF document.

If PDF document does not have AcroForm, this constructor will add an empty AcroForm to the PDF document in order that new fields can be added to the PDF document later.

Parameters
[in]documentA valid PDF document.

◆ initWithOther:()

- (id) initWithOther: (FSForm*)  other

Constructor, with another form object.

Parameters
[in]otherAnother form object.

◆ isEmpty()

- (BOOL) isEmpty

Check whether current object is empty or not.

When the current object is empty, that means current object is useless.

Returns
YES means current object is empty, while NO means not.

◆ moveControl:field_name:()

- (BOOL) moveControl: (FSControl*)  control
field_name: (NSString *)  field_name 

Move the control to a field specified by field name.

Operation of current function for different cases:

  • If the field specified by field name does not exist, a new field will be created with the field name and the control will be moved to this new field.
  • If the field specified by field name exists and the field type is same as the field that control currently belongs to, the control will be combined into this field.
  • If the field specified by field name exists but the field type is different from the field that control currently belongs to, this function will throw exception FSErrConflict.


Parameters
[in]controlA valid form control object.
[in]field_nameA field name. It should not be an empty string.
Returns
YES means success, while NO means failure.

◆ needConstructAppearances()

- (BOOL) needConstructAppearances

Check whether to construct appearance when loading form controls.

Returns
YES means to construct appearances when loading form controls, while NO means not.

◆ removeControl:()

- (void) removeControl: (FSControl*)  control

Remove a form control. (Not support to remove a form control from a signature field)

If the specified form control is the only form control of related form field, the related form field will be removed as well.

Parameters
[in]controlA form control to be removed. If the field type of related form field is FSFieldTypeSignature, this function will throw exception FSErrUnsupported.
Returns
None.

◆ removeField:()

- (void) removeField: (FSField*)  field

Remove a form field. (Not support signature field)

If the form field appears on more than one PDF page, all representations will be removed.
If user wants to remove a signature field, please use function pdf::PDFDoc::removeSignature: instead of current function.

Parameters
[in]fieldA form field to be removed. If the field type is FSFieldTypeSignature, this function will throw exception FSErrUnsupported.
Returns
None.

◆ renameField:new_field_name:()

- (BOOL) renameField: (FSField*)  field
new_field_name: (NSString *)  new_field_name 

Rename a field with a new name.

Parameters
[in]fieldA valid form field object.
[in]new_field_nameA new field name. It should not be an empty string.
Returns
YES means success, while NO means failure.

◆ reset()

- (BOOL) reset

Reset data of all fields (except signature fields) to their default value.

Returns
YES means success, while NO means failure.

◆ setConstructAppearances:()

- (void) setConstructAppearances: (BOOL)  need_construct

Set a flag that specifies whether to construct appearances when loading form controls.

Parameters
[in]need_constructYES means to construct appearances when loading form controls, and NO means not.
Returns
None.

◆ validateFieldName:field_name:()

- (BOOL) validateFieldName: (FSFieldType type
field_name: (NSString *)  field_name 

Validate whether a field name can be used for a new field in specified field type.

This method can be used to check whether a field name can be used for a new field in specified field type. User is recommended to call this function before using function Form::addControl:field_name:field_type:rect: to add a new field with a new control.

Parameters
[in]typeField type, for which the input field name will be validated.
[in]field_nameA string value. It should not be an empty string.

Returns
YES means the input field name is valid for the specified field type, NO means not.

Property Documentation

◆ alignment

- (FSAlignment) alignment
readwritenonatomicassign

Get or Set the alignment value which is used as document-wide default value.

Alignment is a property for variable text. It is only applicable for text field, list box and combo box, which may contain variable text as their content.
If a text field or list box has its own alignment value, the document-wide default alignment value will be ignored; otherwise, the document-wide default value will be used for the text field or list box.

◆ fieldsInCalculationOrder

- (FSFieldArray *) fieldsInCalculationOrder
readwritenonatomicweak

Get or Set an array of form fields in calculation order.

The calculation order defines the order in which the values of fields will be recalculated when value of any field is changed. Usually, these fields have calculation actions.