foxit.pdf.interform.Form Class Reference
Inheritance diagram for foxit.pdf.interform.Form:
foxit.common.Base

Public Member Functions

 Form (PDFDoc document)
 Constructor, with PDF document. More...
 
 Form (Form other)
 Constructor, with another Form object. More...
 
Control AddControl (PDFPage page, string field_name, Field.Type field_type, RectF 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 ExportToXML (string file_path)
 Export the form data to an XML file. More...
 
Alignment GetAlignment ()
 Get the alignment value which is used as document-wide default value. More...
 
Control GetControl (PDFPage page, int index)
 Get a form control by index, in a specified PDF page. More...
 
Control GetControlAtDevicePoint (PDFPage page, PointF point, float tolerance, Field.Type type, Matrix2D matrix)
 Get the form control at a specified position, in device coordination system. More...
 
Control GetControlAtPoint (PDFPage page, PointF point, float tolerance, Field.Type type)
 Get the form control at a specified position, in PDF coordinate system . More...
 
int GetControlCount (PDFPage page)
 Get count of form controls in a specified PDF page. More...
 
DefaultAppearance GetDefaultAppearance ()
 Get the default appearance data. More...
 
PDFDictionary GetDict ()
 Get the dictionary of current object. More...
 
PDFDoc GetDocument ()
 Get the PDF document, with which current form object is associated. More...
 
Field GetField (int index, string filter)
 Get a form field by index, whose names satisfy the specified name filter. More...
 
int GetFieldCount (string filter)
 Get the count of form fields, whose names satisfy the specified name filter. More...
 
FieldArray GetFieldsInCalculationOrder ()
 Get an array of form fields in calculation order. More...
 
Filler GetFormFiller ()
 Get the form filler. More...
 
bool ImportFromXML (string file_path)
 Import the form data from an XML file. More...
 
bool IsEmpty ()
 Check whether current object is empty or not. More...
 
bool NeedConstructAppearances ()
 Check whether to construct appearance when loading form controls. More...
 
void RemoveControl (Control control)
 Remove a form control. (Not support to remove a form control from a signature field) More...
 
void RemoveField (Field field)
 Remove a form field. (Not support signature field) More...
 
bool RenameField (Field field, string 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 SetAlignment (Alignment alignment)
 Set alignment value which is used as document-wide default value. More...
 
void SetConstructAppearances (bool need_construct)
 Set a flag that specifies whether to construct appearances when loading form controls. More...
 
void SetDefaultAppearance (DefaultAppearance default_ap)
 Set default appearance data. More...
 
void SetFieldsInCalculationOrder (FieldArray field_array)
 Set an array of form fields in calculation order. More...
 
bool ValidateFieldName (Field.Type type, string field_name)
 Validate whether a field name can be used for a new field in specified field type. 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 retrieve form fields, please use functions Form::GetFieldCount and Form::GetField.
To retrieve form controls from a PDF page, please use functions Form::GetControlCount and Form::GetControl.
To import form data from an XML file, please use function Form::ImportFromXML; to export form data to an XML file, please use function Form::ExportToXML.
To retrieve form filler object, please use function Form::GetFormFiller.
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 and pdf::PDFDoc::ExportToFDF.
To fill the form, please construct a 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
pdf::PDFDoc
Filler

Constructor & Destructor Documentation

◆ Form() [1/2]

foxit.pdf.interform.Form.Form ( PDFDoc  document)
inline

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
documentA valid PDF document.

◆ Form() [2/2]

foxit.pdf.interform.Form.Form ( Form  other)
inline

Constructor, with another Form object.

Parameters
otherAnother Form object.

Member Function Documentation

◆ AddControl()

Control foxit.pdf.interform.Form.AddControl ( PDFPage  page,
string  field_name,
Field.Type  field_type,
RectF  rect 
)
inline

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 Field or Widget to set properties which will affect appearance. Some setting methods of class Control and Field may directly update appearance, but function annots::Widget::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 = e_HighlightingPush.
check box/radio button: In related widget annotation, border width = 1.0, border style = e_Solid, background color (in the MK dictionary) = 0xFFFFFF, border color (in the MK dictionary) = 0xFFFFFF.

Parameters
pageA valid PDF page, in which the new form control will be added. It should belong to the same PDF document as current form.
field_nameField name.
field_typeField type. Please refer to e_TypeXXX values and this should be one of these values except e_TypeXXX value. If this is e_TypeSignature, this function will throw exception e_ErrUnsupported.
rectRectangle of the new form control which specifies the position in PDF page. It should be in PDF coordinate system .
Returns
The newly added Control object.

◆ ExportToXML()

bool foxit.pdf.interform.Form.ExportToXML ( string  file_path)
inline

Export the form data to an XML file.

Parameters
file_pathA full file_path of an XML file. This specifies the XML file that form data will be exported to.
Returns
true means success, while false means failure.

◆ GetAlignment()

Alignment foxit.pdf.interform.Form.GetAlignment ( )
inline

Get 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 and list 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.

Returns
The alignment value. Please refer to e_AlignmentXXX values and it would be one of these values.

◆ GetControl()

Control foxit.pdf.interform.Form.GetControl ( PDFPage  page,
int  index 
)
inline

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

Parameters
pageA valid PDFPage object. It should belong to the same PDF document as current form.
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 Control object.

◆ GetControlAtDevicePoint()

Control foxit.pdf.interform.Form.GetControlAtDevicePoint ( PDFPage  page,
PointF  point,
float  tolerance,
Field.Type  type,
Matrix2D  matrix 
)
inline

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

Parameters
pageA valid PDFPage object. It should be in the same document as current form.
pointA position, in device coordinate system.
toleranceTolerance value. Valid range: 0.0f to 30.0f.
typeThe field type whose form control will be retrieved. Please refer to e_TypeXXX values and it should be one of these values. e_TypeUnknown means not to care about the field type and just to retrieve the first form control at the specified position.
matrixA transformation matrix. Usually this is returned by function pdf::PDFPage::GetDisplayMatrix. If this is null, current function will have the same feature as function Form::GetControlAtPoint.
Returns
A Control object. If the return value of function Control::IsEmpty for the returned Control object is true, that means no suitable form control is around the specified position.

◆ GetControlAtPoint()

Control foxit.pdf.interform.Form.GetControlAtPoint ( PDFPage  page,
PointF  point,
float  tolerance,
Field.Type  type 
)
inline

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

Parameters
pageA valid PDFPage object. It should be in the same document as current form.
pointA position, in PDF coordinate system .
toleranceTolerance value. Valid range: 0.0f to 30.0f.
typeThe field type whose form control will be retrieved. Please refer to e_TypeXXX values and it should be one of these values. e_TypeUnknown 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 true, that means no suitable form control is around the specified position.

◆ GetControlCount()

int foxit.pdf.interform.Form.GetControlCount ( PDFPage  page)
inline

Get count of form controls in a specified PDF page.

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

◆ GetDefaultAppearance()

DefaultAppearance foxit.pdf.interform.Form.GetDefaultAppearance ( )
inline

Get the default appearance data.

Returns
The default appearance data.

◆ GetDict()

PDFDictionary foxit.pdf.interform.Form.GetDict ( )
inline

Get the dictionary of current object.

Returns
The dictionary of current object.

◆ GetDocument()

PDFDoc foxit.pdf.interform.Form.GetDocument ( )
inline

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

Returns
A PDF document object.

◆ GetField()

Field foxit.pdf.interform.Form.GetField ( int  index,
string  filter 
)
inline

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

Parameters
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.
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 Field object.

◆ GetFieldCount()

int foxit.pdf.interform.Form.GetFieldCount ( string  filter)
inline

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

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

◆ GetFieldsInCalculationOrder()

FieldArray foxit.pdf.interform.Form.GetFieldsInCalculationOrder ( )
inline

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

Returns
An array of form field in calculation order.

◆ GetFormFiller()

Filler foxit.pdf.interform.Form.GetFormFiller ( )
inline

Get the form filler.

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

◆ ImportFromXML()

bool foxit.pdf.interform.Form.ImportFromXML ( string  file_path)
inline

Import the form data from an XML file.

Parameters
file_pathA full file_path of an existing XML file. This specifies the XML file that form data will be imported from.
Returns
true means success, while false means failure.

◆ IsEmpty()

bool foxit.pdf.interform.Form.IsEmpty ( )
inline

Check whether current object is empty or not.

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

Returns
true means current object is empty, while false means not.

◆ NeedConstructAppearances()

bool foxit.pdf.interform.Form.NeedConstructAppearances ( )
inline

Check whether to construct appearance when loading form controls.

Returns
true means to construct appearances when loading form controls, while false means not.

◆ RemoveControl()

void foxit.pdf.interform.Form.RemoveControl ( Control  control)
inline

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
controlA form control to be removed. If the field type of related form field is e_TypeSignature this function will throw exception e_ErrUnsupported.
Returns
None.

◆ RemoveField()

void foxit.pdf.interform.Form.RemoveField ( Field  field)
inline

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
fieldA form field to be removed. If the field type is e_TypeSignature this function will throw exception e_ErrUnsupported.
Returns
None.

◆ RenameField()

bool foxit.pdf.interform.Form.RenameField ( Field  field,
string  new_field_name 
)
inline

Rename a field with a new name.

Parameters
fieldA valid Field object.
new_field_nameA new field name. It should not be an empty string.
Returns
true means success, while false means failure.

◆ Reset()

bool foxit.pdf.interform.Form.Reset ( )
inline

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

Returns
true means success, while false means failure.

◆ SetAlignment()

void foxit.pdf.interform.Form.SetAlignment ( Alignment  alignment)
inline

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

Alignment is a property for variable text. It is only applicable for text field and list 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.

Parameters
alignmentThe new default alignment type of variable text. Please refer to e_AlignmentXXX values and it should be one of these values.
If other values is used to set, e_AlignmentLeft will be used by default.
Returns
None.

◆ SetConstructAppearances()

void foxit.pdf.interform.Form.SetConstructAppearances ( bool  need_construct)
inline

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

Parameters
need_constructtrue means to construct appearances when loading form controls, and false means not.
Returns
None.

◆ SetDefaultAppearance()

void foxit.pdf.interform.Form.SetDefaultAppearance ( DefaultAppearance  default_ap)
inline

Set default appearance data.

Parameters
default_apThe new default appearance.pdf::DefaultAppearance::SetFlags can be used to decide which information is/are to be updated with the new data; for those no updated data, they will keep to use old data.
Returns
None.

◆ SetFieldsInCalculationOrder()

void foxit.pdf.interform.Form.SetFieldsInCalculationOrder ( FieldArray  field_array)
inline

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.

Parameters
field_arrayAn array of form fields to specify the new calculation order.
Returns
None.

◆ ValidateFieldName()

bool foxit.pdf.interform.Form.ValidateFieldName ( Field.Type  type,
string  field_name 
)
inline

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 to add a new field with a new control.

Parameters
typeField type, for which the input field name will be validated.
field_nameA string value. It should not be an empty string.
Returns
true means the input field name is valid for the specified field type, false means not.

Foxit Software Corporation Logo
@2018 Foxit Software Incorporated. All rights reserved.