My Project
|
Public Member Functions | |
Form (const pdf::PDFDoc &document) | |
Constructor, with PDF document. More... | |
Form (const Form &other) | |
Constructor, with another form object. More... | |
~Form () | |
Destructor. | |
Control | AddControl (const PDFPage &page, const wchar_t *field_name, Field::Type field_type, const 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 (const char *file_path) |
Export the form data to an XML file. More... | |
common::Alignment | GetAlignment () const |
Get the alignment value which is used as document-wide default value. More... | |
Control | GetControl (const PDFPage &page, int index) |
Get a form control by index, in a specified PDF page. More... | |
Control | GetControlAtDevicePoint (const PDFPage &page, const PointF &point, float tolerance, Field::Type type, const Matrix *matrix=0) |
Get the form control at a specified position, in device coordination system. More... | |
Control | GetControlAtPoint (const PDFPage &page, const PointF &point, float tolerance, Field::Type type) |
Get the form control at a specified position, in PDF coordinate system. More... | |
int | GetControlCount (const PDFPage &page) const |
Get count of form controls in a specified PDF page. More... | |
DefaultAppearance | GetDefaultAppearance () const |
Get the default appearance data. More... | |
objects::PDFDictionary * | GetDict () const |
Get the dictionary of current object. More... | |
PDFDoc | GetDocument () const |
Get the PDF document, with which current form object is associated. More... | |
Field | GetField (int index, const wchar_t *filter=0) |
Get a form field by index, whose names satisfy the specified name filter. More... | |
int | GetFieldCount (const wchar_t *filter=0) const |
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 () const |
Get the form filler. More... | |
bool | ImportFromXML (const char *file_path) |
Import the form data from an XML file. More... | |
bool | IsEmpty () const |
Check whether current object is empty or not. More... | |
bool | NeedConstructAppearances () const |
Check whether to construct appearance when loading form controls. More... | |
bool | operator != (const Form &other) const |
Not equal operator. More... | |
Form & | operator= (const Form &other) |
Assign operator. More... | |
bool | operator== (const Form &other) const |
Equal operator. 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, const wchar_t *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 (common::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 (const DefaultAppearance &default_ap) |
Set default appearance data. More... | |
void | SetFieldsInCalculationOrder (const FieldArray &field_array) |
Set an array of form fields in calculation order. More... | |
bool | ValidateFieldName (Field::Type type, const WString &field_name) |
Validate whether a field name can be used for a new field in specified field type. More... | |
![]() | |
FS_HANDLE | Handle () const |
Get the handle of current object. More... | |
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 and pdf::PDFDoc::ExportToFDF.
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).
|
explicit |
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.
[in] | document | A valid PDF document. |
foxit::pdf::interform::Form::Form | ( | const Form & | other | ) |
Constructor, with another form object.
[in] | other | Another form object. |
Control foxit::pdf::interform::Form::AddControl | ( | const PDFPage & | page, |
const wchar_t * | field_name, | ||
Field::Type | field_type, | ||
const 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)
Application can use this function to add a new 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 interform::Control and Field 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:
[in] | page | A 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_name | Field name. |
[in] | field_type | Field type. Please refer to values starting from Field::e_TypePushButton and this should be one of these values except Field::e_TypeSignature. If this is Field::e_TypeSignature, this function will throw exception foxit::e_ErrUnsupported. |
[in] | rect | Rectangle of the new form control which specifies the position in PDF page. It should be in PDF coordinate system. |
bool foxit::pdf::interform::Form::ExportToXML | ( | const char * | file_path | ) |
Export the form data to an XML file.
[in] | file_path | A full file_path of an XML file. This specifies the XML file that form data will be exported to. |
common::Alignment foxit::pdf::interform::Form::GetAlignment | ( | ) | const |
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.
Get a form control by index, in a specified PDF page.
[in] | page | A valid PDF page object. It should belong to the same PDF document as current form. |
[in] | index | Index of form control to be retrieved. Valid range: from 0 to (count-1). count is returned by function Field::GetControlCount with same parameter page. |
Control foxit::pdf::interform::Form::GetControlAtDevicePoint | ( | const PDFPage & | page, |
const PointF & | point, | ||
float | tolerance, | ||
Field::Type | type, | ||
const Matrix * | matrix = 0 |
||
) |
Get the form control at a specified position, in device coordination system.
[in] | page | A valid PDF page object. It should be in the same document as current form. |
[in] | point | A position, in device coordinate system. |
[in] | tolerance | Tolerance value. Valid range: 0.0f to 30.0f. |
[in] | type | The field type whose form control will be retrieved. Please refer to values starting from Field::e_TypeUnknown and this should be one of these values. Field::e_TypeUnknown means not to care about the field type and just to retrieve the first form control at the specified position. |
[in] | matrix | A 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. Default value: NULL. |
Control foxit::pdf::interform::Form::GetControlAtPoint | ( | const PDFPage & | page, |
const PointF & | point, | ||
float | tolerance, | ||
Field::Type | type | ||
) |
Get the form control at a specified position, in PDF coordinate system.
[in] | page | A valid PDF page object. It should be in the same document as current form. |
[in] | point | A position, in PDF coordinate system. |
[in] | tolerance | Tolerance value. Valid range: 0.0f to 30.0f. |
[in] | type | The field type whose form control will be retrieved. Please refer to values starting from Field::e_TypeUnknown and this should be one of these values. Field::e_TypeUnknown means not to care about the field type and just to retrieve the first form control at the specified position. |
int foxit::pdf::interform::Form::GetControlCount | ( | const PDFPage & | page | ) | const |
Get count of form controls in a specified PDF page.
[in] | page | A valid PDF page object. It should belong to the same PDF document as current form. |
DefaultAppearance foxit::pdf::interform::Form::GetDefaultAppearance | ( | ) | const |
Get the default appearance data.
objects::PDFDictionary* foxit::pdf::interform::Form::GetDict | ( | ) | const |
Get the dictionary of current object.
PDFDoc foxit::pdf::interform::Form::GetDocument | ( | ) | const |
Get the PDF document, with which current form object is associated.
Field foxit::pdf::interform::Form::GetField | ( | int | index, |
const wchar_t * | filter = 0 |
||
) |
Get a form field by index, whose names satisfy the specified name filter.
[in] | index | Index 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] | filter | A 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. Default value: an empty string. |
int foxit::pdf::interform::Form::GetFieldCount | ( | const wchar_t * | filter = 0 | ) | const |
Get the count of form fields, whose names satisfy the specified name filter.
[in] | filter | A 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. Default value: an empty string. |
FieldArray foxit::pdf::interform::Form::GetFieldsInCalculationOrder | ( | ) |
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.
Filler foxit::pdf::interform::Form::GetFormFiller | ( | ) | const |
Get the form filler.
bool foxit::pdf::interform::Form::ImportFromXML | ( | const char * | file_path | ) |
Import the form data from an XML file.
[in] | file_path | A full file_path of an existing XML file. This specifies the XML file that form data will be imported from. |
bool foxit::pdf::interform::Form::IsEmpty | ( | ) | const |
Check whether current object is empty or not.
When the current object is empty, that means current object is useless.
bool foxit::pdf::interform::Form::NeedConstructAppearances | ( | ) | const |
Check whether to construct appearance when loading form controls.
bool foxit::pdf::interform::Form::operator != | ( | const Form & | other | ) | const |
Not equal operator.
[in] | other | Another other object. This function will check if current object is not equal to this one. |
Assign operator.
[in] | other | Another form object, whose value would be assigned to current object. |
bool foxit::pdf::interform::Form::operator== | ( | const Form & | other | ) | const |
Equal operator.
[in] | other | Another other object. This function will check if current object is equal to this one. |
void foxit::pdf::interform::Form::RemoveControl | ( | Control & | 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.
[in] | control | A form control to be removed. If the field type of related form field is Field::e_TypeSignature, this function will throw exception foxit::e_ErrUnsupported. |
void foxit::pdf::interform::Form::RemoveField | ( | Field & | 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.
[in] | field | A form field to be removed. If the field type is Field::e_TypeSignature, this function will throw exception foxit::e_ErrUnsupported. |
bool foxit::pdf::interform::Form::RenameField | ( | Field & | field, |
const wchar_t * | new_field_name | ||
) |
Rename a field with a new name.
[in] | field | A valid form field object. |
[in] | new_field_name | A new field name. It should not be an empty string. |
bool foxit::pdf::interform::Form::Reset | ( | ) |
Reset data of all fields (except signature fields) to their default value.
void foxit::pdf::interform::Form::SetAlignment | ( | common::Alignment | alignment | ) |
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.
[in] | alignment | The new default alignment type of variable text. Please refer to values starting from common::e_AlignmentLeft and this should be one of these values. If other values is used to set, common::e_AlignmentLeft will be used by default. |
void foxit::pdf::interform::Form::SetConstructAppearances | ( | bool | need_construct | ) |
Set a flag that specifies whether to construct appearances when loading form controls.
[in] | need_construct | true means to construct appearances when loading form controls, and false means not. |
void foxit::pdf::interform::Form::SetDefaultAppearance | ( | const DefaultAppearance & | default_ap | ) |
Set default appearance data.
[in] | default_ap | The new default appearance. flags of input data 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. |
void foxit::pdf::interform::Form::SetFieldsInCalculationOrder | ( | const FieldArray & | field_array | ) |
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.
[in] | field_array | An array of form fields to specify the new calculation order. |
bool foxit::pdf::interform::Form::ValidateFieldName | ( | Field::Type | type, |
const WString & | 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 to add a new field with a new control.
[in] | type | Field type, for which the input field name will be validated. |
[in] | field_name | A string value. It should not be an empty string. |