Foxit PDF SDK

Public Types | Public Member Functions | List of all members
foxit::addon::xfa::XFADoc Class Reference
Inheritance diagram for foxit::addon::xfa::XFADoc:

## Public Types
enum | EventType { e_EventTypeUnknown = 0, e_EventTypePostPrint = 1, e_EventTypePrePrint = 2, e_EventTypeClick = 3, e_EventTypeChange = 4, e_EventTypeDocClose = 5, e_EventTypeDocReady = 6, e_EventTypeEnter = 7, e_EventTypeExit = 8, e_EventTypeFull = 9, e_EventTypeIndexChange = 10, e_EventTypeInitialize = 11, e_EventTypeMouseDown = 12, e_EventTypeMouseEnter = 13, e_EventTypeMouseExit = 14, e_EventTypeMouseUp = 15, e_EventTypePostExecute = 16, e_EventTypePostOpen = 17, e_EventTypePostSave = 18, e_EventTypePostSign = 19, e_EventTypePostSubmit = 20, e_EventTypePreExecute = 21, e_EventTypePreOpen = 22, e_EventTypePreSave = 23, e_EventTypePreSign = 24, e_EventTypePreSubmit = 25, e_EventTypeReady = 26, e_EventTypeValidationState = 27, e_EventTypeInitCalculate = 28, e_EventTypeInitVariables = 29, e_EventTypeCalculate = 30, e_EventTypeValidate = 31 }
| Enumeration for XFA event type. More...
enum | ExportDataType { e_ExportDataTypeXML = 0, e_ExportDataTypeStaticXDP = 1, e_ExportDataTypeXDP = 2 }
| Enumeration for the type of exported data. More...
enum | Type { e_Dynamic = 0, e_Static = 1, e_XDP = 2 }
| Enumeration for XFA document type. More...

## Public Member Functions
| XFADoc (const foxit::pdf::PDFDoc &document)
| Constructor. More...
| XFADoc (const pdf::PDFDoc &document, DocProviderCallback *xfa_doc_provider_handler)
| Constructor. More...
| XFADoc (const XFADoc &other)
| Constructor, with another XFA document object. More...
| ~XFADoc ()
| Destructor.
bool | ExportData (const char *output_file_path, ExportDataType export_type)
| Export data to a file. More...
bool | ExportData (const wchar_t *output_file_path, ExportDataType export_type)
| Export data to a file. More...
bool | ExportData (foxit::common::file::WriterCallback *stream, ExportDataType export_type)
| Export data to a common::file::WriterCallback object. More...
void | FlattenTo (const char *output_file_path)
| Flatten current XFA document to a file. More...
void | FlattenTo (const wchar_t *output_file_path)
| Flatten current XFA document to a file. More...
void | FlattenTo (foxit::common::file::StreamCallback *stream)
| Flatten current XFA document to a file stream. More...
XFAPage | GetPage (int page_index)
| Get XFA page by index. More...
int | GetPageCount () const
| Get XFA page count. More...
Type | GetType () const
| Get the XFA document type. More...
XFAWidget | GetWidgetByFullName (const WString &full_name)
| Get the XFA widget which matches the specified full name. More...
bool | ImportData (const char *file_path)
| Import data from an XML or XDP file. More...
bool | ImportData (const wchar_t *file_path)
| Import data from an XML or XDP file. More...
bool | ImportData (foxit::common::file::ReaderCallback *file_reader)
| Import data from a common::file::ReaderCallback object. More...
bool | IsEmpty () const
| Check whether current object is empty or not. More...
void | KillFocus ()
| Kill the focus of XFA widget. More...
bool | operator!= (const XFADoc &other) const
| Not equal operator. More...
XFADoc & | operator= (const XFADoc &other)
| Assign operator. More...
bool | operator== (const XFADoc &other) const
| Equal operator. More...
void | ProcessEvent (EventType event_type)
| Process a kind of event for all the XFA widgets in current XFA document. More...
void | ResetForm ()
| Reset form. More...
void | SetDocProviderCallback (foxit::addon::xfa::DocProviderCallback *doc_provider_callback)
| Set XFA document provider callback. More...
void | SetFocus (XFAWidget xfa_widget)
| Set the focus of XFA widget. More...
void | SetPDFPath (const char *pdf_file_path)
| Set the path of related PDF document. More...
void | SetPDFPath (const wchar_t *pdf_file_path)
| Set the path of related PDF document. More...
common::Progressive | StartLoad (common::PauseCallback *pause=0)
| Start to load content for current XFA document. More...
Public Member Functions inherited from foxit::Base
FS_HANDLE | Handle () const
| Get the handle of current object. More...

## Detailed Description

Class XFADoc is constructed from a loaded PDF document object, in order to access XFA content more clearly. User must call common::Library::RegisterXFAAppProviderCallback before using XFA moudle. For a newly constructed XFA object, please remember to call function XFADoc::StartLoad before using other functions in class XFA.
To search among an XFA document, please construct a pdf::TextSearch object with XFADoc object.

See also
  pdf::TextSearch

## Member Enumeration Documentation

## ◆ EventType

enum foxit::addon::xfa::XFADoc::EventType

Enumeration for XFA event type.

Values of this enumeration should be used alone.

Enumerator
e_EventTypeUnknown | Event type: Unknown.
e_EventTypePostPrint | This kind of event is triggered just after the rendered form has been sent to the printer, spooler, or output destination.
e_EventTypePrePrint | This kind of event is triggered just before the rendering for printing begins.
e_EventTypeClick | This kind of event is triggered when the user clicks in the field.
e_EventTypeChange | This kind of event is triggered when the user changes the field value.
e_EventTypeDocClose | This kind of event is triggered at the very end of processing if and only if all validations succeeded.
e_EventTypeDocReady | This kind of event is triggered before the document is rendered but after data binding.
e_EventTypeEnter | This kind of event is triggered when the field gains keyboard focus, whether caused by a user action (tabbing into the field or clicking on it with the mouse) or by a script programmatically setting the preSubmit event applies only to the Form DOM ($form).
e_EventTypeExit | This kind of event is triggered when keyboard focus is yielded from a field directly or indirectly within the subform to a field or other object outside the subform.
e_EventTypeFull | This kind of event is triggered when the user has entered the maximum allowed amount of content into the field and tries to enter more content.
e_EventTypeIndexChange | This kind of event is triggered to tell an object that it has just been added to an array or that its position in the array (its subscript) has changed.
e_EventTypeInitialize | This kind of event is triggered after data binding is complete.
e_EventTypeMouseDown | This kind of event is triggered when the mouse button is depressed at a moment and the mouse pointer is within the region.
e_EventTypeMouseEnter | This kind of event is triggered when the user moves the mouse pointer into the region of the field, without necessarily pressing the mouse button.
e_EventTypeMouseExit | This kind of event is triggered when user moves the mouse pointer out of the field, whether the mouse button is depressed or not.
e_EventTypeMouseUp | This kind of event is triggered when the mouse button is released at a moment and the mouse pointer is within the region.
e_EventTypePostExecute | This kind of event is triggered after a successful WSDL transaction, just after the reply to the request has been received and the received data is marshalled in the Connection Data DOM.
e_EventTypePostOpen | This kind of event is related to pre-open event for drop-down choice lists.
e_EventTypePostSave | This kind of event is triggered just after the form has been written out in PDF or XDP format.
e_EventTypePostSign | This kind of event is triggered after successfully applying a signature.
e_EventTypePostSubmit | This kind of event is triggered just after the returned data has been marshalled in the Connection Data DOM.
e_EventTypePreExecute | This kind of event is triggered when a request is sent to a web service via WSDL, just after the data has been marshalled in the Connection Data DOM but before the request has been sent.
e_EventTypePreOpen | This kind of event applies only to drop-down choice lists for which open="userControl" or open="onEntry". The event is intended to trigger scripts that add choices to and remove choices from the choice list.
e_EventTypePreSave | This kind of event is triggered just before the form data is written out in PDF or XDP format.
e_EventTypePreSign | This kind of event is triggered when a signature is about to be applied.
e_EventTypePreSubmit | This kind of event is triggered just after the data has been marshalled in the Connection Data DOM but before validation and before the data is submitted to the host.
e_EventTypeReady | This kind of event is triggered after an XFA DOM has finished loading.
e_EventTypeValidationState | This kind of event is triggered whenever the validation state of the target changes.
e_EventTypeInitCalculate | This kind of event represents the first run calculate.
e_EventTypeInitVariables | This kind of event is not a real event activity, just sign script in variables.
e_EventTypeCalculate | This kind of event represents a calculate operation.
e_EventTypeValidate | This kind of event represents a validate operation.

## ◆ ExportDataType

enum foxit::addon::xfa::XFADoc::ExportDataType

Enumeration for the type of exported data.

Values of this enumeration should be used alone.

Enumerator
e_ExportDataTypeXML | Type of exported data: XML.
e_ExportDataTypeStaticXDP | Type of exported data: Static XDP.
e_ExportDataTypeXDP | Type of exported data: XDP.

## ◆ Type

enum foxit::addon::xfa::XFADoc::Type

Enumeration for XFA document type.

Values of this enumeration should be used alone.

Enumerator
e_Dynamic | XFA document type: Dynamic.
e_Static | XFA document type: Static.
e_XDP | XFA document type: XDP, as Raw XML data.

## Constructor & Destructor Documentation

## ◆ XFADoc() [1/3]

foxit::addon::xfa::XFADoc::XFADoc | ( | const pdf::PDFDoc & | document,
|  | DocProviderCallback * | xfa_doc_provider_handler
| ) |  |

Constructor.

Parameters

  [in] | document | A valid PDF document. It should has been loaded successfully.
  [in] | xfa_doc_provider_handler | An XFA document provider callback object which is implemented by user and based on callback class DocProviderCallback. It should not be NULL. User should ensure this callback object is kept valid until related PDF document is released.

Note
  If module "XFA" is not defined in the license information which is used in function common::Library::Initialize, that means user has no right in using XFA related functions and this constructor will throw exception foxit::e_ErrNoXFAModuleRight.

## ◆ XFADoc() [2/3]

foxit::addon::xfa::XFADoc::XFADoc | ( | const foxit::pdf::PDFDoc & | document | ) |

Constructor.

When constructing an XFADoc by this constructor successfully, user must set XFA document provider callback by function XFADoc::SetDocProviderCallback.

Parameters

  [in] | document | A valid PDF document. It should has been loaded successfully.

Note
  If module "XFA" is not defined in the license information which is used in function common::Library::Initialize, that means user has no right in using XFA related functions and this constructor will throw exception foxit::e_ErrNoXFAModuleRight.

## ◆ XFADoc() [3/3]

foxit::addon::xfa::XFADoc::XFADoc | ( | const XFADoc & | other | ) |

Constructor, with another XFA document object.

Parameters

  [in] | other | Another XFA document object

## Member Function Documentation

## ◆ ExportData() [1/3]

bool foxit::addon::xfa::XFADoc::ExportData | ( | const char * | output_file_path,
|  | ExportDataType | export_type
| ) |  |

Export data to a file.

Parameters

  [in] | output_file_path | A file path, to which data will be exported to.
  [in] | export_type | Export type. Please refer to values starting from XFADoc::e_ExportDataTypeXML and this should be one of these values.

Returns
  true means success, while false means failure.

## ◆ ExportData() [2/3]

bool foxit::addon::xfa::XFADoc::ExportData | ( | const wchar_t * | output_file_path,
|  | ExportDataType | export_type
| ) |  |

Export data to a file.

Parameters

  [in] | output_file_path | A file path, to which data will be exported to.
  [in] | export_type | Export type. Please refer to values starting from XFADoc::e_ExportDataTypeXML and this should be one of these values.

Returns
  true means success, while false means failure.

## ◆ ExportData() [3/3]

bool foxit::addon::xfa::XFADoc::ExportData | ( | foxit::common::file::WriterCallback * | stream,
|  | ExportDataType | export_type
| ) |  |

Export data to a common::file::WriterCallback object.

Parameters

  [in] | stream | A foxit::common::file::WriterCallback object which is implemented by user to save the exported data.
  [in] | export_type | Export type. Please refer to values starting from XFADoc::e_ExportDataTypeXML and this should be one of these values.

Returns
  true means success, while false means failure.

## ◆ FlattenTo() [1/3]

void foxit::addon::xfa::XFADoc::FlattenTo | ( | const char * | output_file_path | ) |

Flatten current XFA document to a file.

Parameters

  [in] | output_file_path | A file path, to which the flattening result will be saved.

Returns
  None.

## ◆ FlattenTo() [2/3]

void foxit::addon::xfa::XFADoc::FlattenTo | ( | const wchar_t * | output_file_path | ) |

Flatten current XFA document to a file.

Parameters

  [in] | output_file_path | A file path, to which the flattening result will be saved.

Returns
  None.

## ◆ FlattenTo() [3/3]

void foxit::addon::xfa::XFADoc::FlattenTo | ( | foxit::common::file::StreamCallback * | stream | ) |

Flatten current XFA document to a file stream.

Parameters

  [in] | stream | A foxit::common::file::StreamCallback object which is implemented by user to save the flattened result.

Returns
  None.

## ◆ GetPage()

XFAPage foxit::addon::xfa::XFADoc::GetPage | ( | int | page_index | ) |

Get XFA page by index.

Parameters

  [in] | page_index | The page index. Valid range: from 0 to (count-1). count is returned by function XFADoc::GetPageCount.

Returns
  The XFA page.

## ◆ GetPageCount()

int foxit::addon::xfa::XFADoc::GetPageCount | ( |  | ) | const

Get XFA page count.

Returns
  Page count.

## ◆ GetType()

Type foxit::addon::xfa::XFADoc::GetType | ( |  | ) | const

Get the XFA document type.

Returns
  The type of XFA document. Please refer to values starting from XFADoc::e_Dynamic and this would be one of these values.

## ◆ GetWidgetByFullName()

XFAWidget foxit::addon::xfa::XFADoc::GetWidgetByFullName | ( | const WString & | full_name | ) |

Get the XFA widget which matches the specified full name.

Some XFA widgets may cover serveral XFA pages. In this case, this function can only be used to get the first matched XFA widget in XFA document. User can also use function XFAPage::GetWidgetByFullName to get the matched XFA widget in an XFA page.

Parameters

  [in] | full_name | An XFA widget's full name. It should not be an empty string. XFA widget's full name can be retrieved by function XFAWidget::GetName with type XFAWidget::e_WidgetNameTypeFullName in previous process.

Returns
  An XFA Widget object.

## ◆ ImportData() [1/3]

bool foxit::addon::xfa::XFADoc::ImportData | ( | const char * | file_path | ) |

Import data from an XML or XDP file.

Parameters

  [in] | file_path | A path of a source file, whose data will be imported to current XFA document. It should be XML or XDP file and the file extension should be ".xml" or ".xdp".

Returns
  true means success, while false means failure.

## ◆ ImportData() [2/3]

bool foxit::addon::xfa::XFADoc::ImportData | ( | const wchar_t * | file_path | ) |

Import data from an XML or XDP file.

Parameters

  [in] | file_path | A path of a source file, whose data will be imported to current XFA document. It should be XML or XDP file and the file extension should be ".xml" or ".xdp".

Returns
  true means success, while false means failure.

## ◆ ImportData() [3/3]

bool foxit::addon::xfa::XFADoc::ImportData | ( | foxit::common::file::ReaderCallback * | file_reader | ) |

Import data from a common::file::ReaderCallback object.

Parameters

  [in] | file_reader | A common::file::ReaderCallback object, whose data will be imported to current XFA document. It should be XML or XDP file.

Returns
  true means success, while false means failure.

## ◆ IsEmpty()

bool foxit::addon::xfa::XFADoc::IsEmpty | ( |  | ) | const

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.

## ◆ KillFocus()

void foxit::addon::xfa::XFADoc::KillFocus | ( |  | ) |

Kill the focus of XFA widget.

Returns
  None.

## ◆ operator!=()

bool foxit::addon::xfa::XFADoc::operator!= | ( | const XFADoc & | other | ) | const

Not equal operator.

Parameters

  [in] | other | Another XFA document object. This function will check if current object is not equal to this one.

Returns
  true means not equal, while false means equal.

## ◆ operator=()

XFADoc& foxit::addon::xfa::XFADoc::operator= | ( | const XFADoc & | other | ) |

Assign operator.

Parameters

  [in] | other | Another XFA document object, whose value would be assigned to current object.

Returns
  Reference to current object itself.

## ◆ operator==()

bool foxit::addon::xfa::XFADoc::operator== | ( | const XFADoc & | other | ) | const

Equal operator.

Parameters

  [in] | other | Another XFA document object. This function will check if current object is equal to this one.

Returns
  true means equal, while false means not equal.

## ◆ ProcessEvent()

void foxit::addon::xfa::XFADoc::ProcessEvent | ( | EventType | event_type | ) |

Process a kind of event for all the XFA widgets in current XFA document.

Parameters

  [in] | event_type | An event type. Please refer to values starting from XFADoc::e_EventTypePostPrint and this should be one of these values except XFADoc::e_EventTypeUnknown. Currently, only XFADoc::e_EventTypePostPrint and XFADoc::e_EventTypePrePrint are supported.

Returns
  None.

## ◆ ResetForm()

void foxit::addon::xfa::XFADoc::ResetForm | ( |  | ) |

Reset form.

Returns
  None.

## ◆ SetDocProviderCallback()

void foxit::addon::xfa::XFADoc::SetDocProviderCallback | ( | foxit::addon::xfa::DocProviderCallback * | doc_provider_callback | ) |

Set XFA document provider callback.

Parameters

  [in] | doc_provider_callback | An XFA document provider callback object which is implemented by user and based on callback class DocProviderCallback. It should not be NULL. User should ensure this callback object is kept valid until related PDF document is released.

Returns
  None.

## ◆ SetFocus()

void foxit::addon::xfa::XFADoc::SetFocus | ( | XFAWidget | xfa_widget | ) |

Set the focus of XFA widget.

Parameters

  [in] | xfa_widget | An XFA widget which would be focused.

Returns
  None.

## ◆ SetPDFPath() [1/2]

void foxit::addon::xfa::XFADoc::SetPDFPath | ( | const char * | pdf_file_path | ) |

Set the path of related PDF document.

The PDF path will be used in function XFADoc::ExportData, to be a part of exported data.

Parameters

  [in] | pdf_file_path | The file path of related PDF document. It can be either an absolute path or a relative path. It should not be an empty string.

Returns
  None.

## ◆ SetPDFPath() [2/2]

void foxit::addon::xfa::XFADoc::SetPDFPath | ( | const wchar_t * | pdf_file_path | ) |

Set the path of related PDF document.

The PDF path will be used in function XFADoc::ExportData, to be a part of exported data.

Parameters

  [in] | pdf_file_path | The file path of related PDF document. It can be either an absolute path or a relative path. It should not be an empty string.

Returns
  None.

## ◆ StartLoad()

common::Progressive foxit::addon::xfa::XFADoc::StartLoad | ( | common::PauseCallback * | pause = `0` | ) |

Start to load content for current XFA document.

It may take a long time to loading XFA content, so this function uses a progressive process to do this.
The related PDF document object has been loaded, but only PDF related contents have been loaded. So, in order to access XFA content, this function should be called to load XFA content.

Parameters

  [in] | pause | Pause object which decides if the importing process needs to be paused. This can be NULL which means not to pause during the parsing process. If this is not NULL, it should be a valid pause object implemented by user. Default value: NULL.

Returns
  A progressive object. Please check the rate of current progress by function common::Progressive::GetRateOfProgress. If the rate is not 100 yet, call function common::Progressive::Continue to continue the progress until the progress is finished.