Foxit PDF SDK
fs_pdfform.h
Go to the documentation of this file.
1 
15 #ifndef FS_PDFFORM_H_
16 #define FS_PDFFORM_H_
17 
18 #include "common/fs_common.h"
19 #include "fdf/fs_fdfdoc.h"
22 
28 namespace foxit {
32 namespace pdf {
33 class PDFDoc;
34 class PDFPage;
38 namespace interform {
39 // forward declaration
40 class Control;
41 class Field;
42 
44 FSDK_DEFINE_ARRAY(FieldArray,Field)
45 
46 
47 class ChoiceOption FS_FINAL : public Object {
48  public:
51  : option_value(WString())
52  , option_label(WString())
53  , selected(false)
54  , default_selected(false) {}
55 
66  ChoiceOption(const wchar_t* option_value, const wchar_t* option_label, bool selected, bool default_selected)
67  : option_value(option_value)
68  , option_label(option_label)
69  , selected(selected)
70  , default_selected(default_selected) {}
71 
77  ChoiceOption(const ChoiceOption& option)
78  : option_value(option.option_value)
79  , option_label(option.option_label)
80  , selected(option.selected)
81  , default_selected(option.default_selected) {}
82 
90  ChoiceOption& operator = (const ChoiceOption& option) {
91  option_value = option.option_value;
92  option_label = option.option_label;
93  selected = option.selected;
94  default_selected = option.default_selected;
95  return *this;
96  }
97 
110  void Set(const wchar_t* option_value, const wchar_t* option_label, bool selected, bool default_selected) {
111  this->option_value = option_value;
112  this->option_label = option_label;
113  this->selected = selected;
114  this->default_selected = default_selected;
115  }
118 
121 
123  bool selected;
124 
127 };
128 
130 FSDK_DEFINE_ARRAY(ChoiceOptionArray, ChoiceOption)
131 
132 
145 class Field : public Base {
146  public:
152  typedef enum _Type {
154  e_TypeUnknown = 0,
156  e_TypePushButton = 1,
158  e_TypeCheckBox = 2,
160  e_TypeRadioButton = 3,
162  e_TypeComboBox = 4,
164  e_TypeListBox = 5,
166  e_TypeTextField = 6,
168  e_TypeSignature = 7
169  } Type;
170 
176  typedef enum _Flags {
183  e_FlagReadOnly = 0x01,
185  e_FlagRequired = 0x02,
187  e_FlagNoExport = 0x04,
193  e_FlagButtonNoToggleToOff = 0x100,
199  e_FlagButtonRadiosInUnison = 0x200,
204  e_FlagTextMultiline = 0x100,
212  e_FlagTextPassword = 0x200,
217  e_FlagTextFileSelect = 0x400,
219  e_FlagTextNoSpellCheck = 0x800,
225  e_FlagTextDoNotScroll = 0x1000,
231  e_FlagTextComb = 0x2000,
236  e_FlagComboEdit = 0x100,
241  e_FlagChoiceMultiSelect = 0x100,
243  e_FlagTextRichText = 0x4000,
245  e_FlagChoiceSort = 0x200,
250  e_FlagChoiceCommitOnSelChange = 0x400
251  } Flags;
252 
253 
261  Field(const PDFDoc& document, objects::PDFDictionary* field_dict);
262 
268  Field(const Field& field);
276  Field& operator = (const Field& other);
277 
285  bool operator == (const Field& other) const;
293  bool operator != (const Field& other) const;
294 
296  ~Field();
297 
305  bool IsEmpty() const;
306 
313  Type GetType() const;
314 
323  uint32 GetFlags() const;
324 
335  void SetFlags(uint32 flags);
336 
342  WString GetName() const;
343 
352  WString GetDefaultValue() const;
353 
364  void SetDefaultValue(const wchar_t* value);
365 
376  WString GetValue() const;
377 
403  void SetValue(const wchar_t* value);
404 
417  common::Alignment GetAlignment() const;
418 
435  void SetAlignment(common::Alignment alignment);
436 
447  WString GetAlternateName() const;
448 
462  void SetAlternateName(const wchar_t* alternate_name);
463 
469  DefaultAppearance GetDefaultAppearance() const;
470 
482  void SetDefaultAppearance(const DefaultAppearance& default_ap);
483 
491  WString GetMappingName() const;
492 
503  void SetMappingName(const wchar_t* name);
504 
512  int GetMaxLength() const;
513 
523  void SetMaxLength(int max_length);
524 
533  ChoiceOptionArray GetOptions() const;
534 
545  void SetOptions(const ChoiceOptionArray& option_array);
546 
556  int GetTopVisibleIndex();
557 
569  void SetTopVisibleIndex(int index);
570 
576  int GetControlCount() const;
577 
586  Control GetControl(int index);
587 
595  int GetControlCount(const foxit::pdf::PDFPage& page) const;
596 
607  Control GetControl(const foxit::pdf::PDFPage& page, int index);
608 
614  bool Reset();
615 
621  objects::PDFDictionary* GetDict() const;
622 
632  objects::PDFObject* GetValueObj() const;
633 
643  objects::PDFObject* GetDefaultValueObj() const;
644 
656  objects::PDFObject* GetInheritedAttribute(const char* attribute_name) const;
657 
658  // User is strongly recommended NOT to use this method; otherwise unknown situation may occur.
659  explicit Field(FS_HANDLE handle = NULL);
660 };
661 
687 class Form FS_FINAL : public Base {
688  public:
697  explicit Form(const pdf::PDFDoc& document);
703  Form(const Form& other);
711  Form& operator = (const Form& other);
712 
720  bool operator == (const Form& other) const;
728  bool operator != (const Form& other) const;
729 
731  ~Form();
732 
740  bool IsEmpty() const;
741 
754 
769  void SetAlignment(common::Alignment alignment);
770 
776  bool NeedConstructAppearances() const;
777 
786  void SetConstructAppearances(bool need_construct);
787 
806  Control GetControlAtDevicePoint(const PDFPage& page, const PointF& point, float tolerance, Field::Type type,
807  const Matrix* matrix = NULL);
808 
823  Control GetControlAtPoint(const PDFPage& page, const PointF& point, float tolerance, Field::Type type);
824 
831 
843  void SetDefaultAppearance(const DefaultAppearance& default_ap);
844 
850  PDFDoc GetDocument() const;
851 
861 
872  void SetFieldsInCalculationOrder(const FieldArray& field_array);
873 
886  bool ValidateFieldName(Field::Type type, const WString& field_name);
887 
896  bool RenameField(Field& field, const wchar_t* new_field_name);
897 
944  Control AddControl(const PDFPage& page, const wchar_t* field_name, Field::Type field_type, const RectF& rect);
945 
965  bool MoveControl(Control& control, const wchar_t* field_name);
966 
979  void RemoveField(Field& field);
980 
992  void RemoveControl(Control& control);
993 
1006  int GetFieldCount(const wchar_t* filter = NULL) const;
1007 
1023  Field GetField(int index, const wchar_t* filter = NULL);
1024 
1032  int GetControlCount(const PDFPage& page) const;
1033 
1044  Control GetControl(const PDFPage& page, int index);
1045 
1046 #ifndef _FX_NO_JSE_
1047 
1054  Filler GetFormFiller() const;
1055 #endif // #ifndef _FX_NO_JSE_
1056 
1062  bool Reset();
1063 
1072  bool ExportToXML(const char* file_path);
1073 
1086  bool ExportToXML(const wchar_t* file_path, const FieldArray& field_array, bool is_include);
1087 
1101  bool ExportToXML(foxit::common::file::WriterCallback* xml_file, const FieldArray& field_array, bool is_include);
1102 
1111  bool ImportFromXML(const char* file_path);
1112 
1125  bool ExportToCSV(const wchar_t* csv_file_path, const wchar_t* pdf_file_name, bool is_append);
1126 
1139  bool ExportToCSV(foxit::common::file::StreamCallback* csv_file, const wchar_t* pdf_file_name, bool is_append);
1140 
1154  bool ExportToHTML(const wchar_t* html_file_path, const FieldArray& field_array, bool is_include);
1155 
1169  bool ExportToHTML(foxit::common::file::WriterCallback* html_file, const FieldArray& field_array, bool is_include);
1170 
1184  bool ExportToTXT(const wchar_t* txt_file_path, const FieldArray& field_array, bool is_include);
1185 
1199  bool ExportToTXT(foxit::common::file::WriterCallback* txt_file, const FieldArray& field_array, bool is_include);
1200 
1207 
1218  void FixPageFields(int page_index);
1219 
1220  // User is strongly recommended NOT to use this method; otherwise unknown situation may occur.
1221  explicit Form(FS_HANDLE handle = NULL);
1222 };
1223 
1239 class Control FS_FINAL : public Base {
1240  public:
1246  Control(const Control& other);
1254  Control& operator = (const Control& other);
1255 
1263  bool operator == (const Control& other) const;
1271  bool operator != (const Control& other) const;
1272 
1274  ~Control();
1275 
1283  bool IsEmpty() const;
1284 
1290  Field GetField() const;
1291 
1298 
1304  annots::Widget GetWidget() const;
1305 
1311  int GetIndex() const;
1312 
1321  WString GetExportValue() const;
1322 
1333  void SetExportValue(const wchar_t* value);
1334 
1343  bool IsChecked() const;
1344 
1355  void SetChecked(bool checked_status);
1356 
1366  bool IsDefaultChecked() const;
1367 
1378  void SetDefaultChecked(bool checked_status);
1379 
1386 
1398  void SetDefaultAppearance(const DefaultAppearance& default_ap);
1399 
1413 
1429  void SetAlignment(common::Alignment alignment);
1430 
1431  // User is strongly recommended NOT to use this method; otherwise unknown situation may occur.
1432  explicit Control(FS_HANDLE handle = NULL);
1433 
1434 };
1435 } // namespace interform
1436 } // namespace pdf
1437 } // namespace foxit
1438 #endif // FS_PDFFORM_H_
1439 
Control GetControl(const PDFPage &page, int index)
Get a form control by index, in a specified PDF page.
void SetChecked(bool checked_status)
Set the check state of current form control when related form field is check box or radio button.
int GetIndex() const
Get the index of current form control among all the controls of related form field.
objects::PDFDictionary * GetWidgetDict() const
Get the dictionary of related widget annotation.
void Set(const wchar_t *option_value, const wchar_t *option_label, bool selected, bool default_selected)
Set value.
Definition: fs_pdfform.h:110
File writing interface.
Definition: fx_stream.h:451
DefaultAppearance GetDefaultAppearance() const
Get the default appearance data.
bool IsEmpty() const
Check whether current object is empty or not.
bool ExportToHTML(const wchar_t *html_file_path, const FieldArray &field_array, bool is_include)
Export data of specified form fields to an HTML file.
Filler GetFormFiller() const
Get the form filler.
CFX_Object Object
Object type.
Definition: fs_basictypes.h:217
Header file for form filler related definitions and classes.
common::Alignment GetAlignment() const
Get the alignment value which is used as document-wide default value.
void SetExportValue(const wchar_t *value)
Set export mapping name when related form field is check box or radio button.
bool IsDefaultChecked() const
Check if the current form control is checked by default when related form field is check box or radio...
Header file for FDF doucument related definitions and classes.
bool default_selected
Used to indicate whether the option would be selected by default or not.
Definition: fs_pdfform.h:126
Definition: fs_formfiller.h:271
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 coordinate system.
void SetDefaultChecked(bool checked_status)
Set the default check state of current form control when related form field is check box or radio but...
Definition: fx_coordinates.h:30
ChoiceOption(const wchar_t *option_value, const wchar_t *option_label, bool selected, bool default_selected)
Constructor, with parameters.
Definition: fs_pdfform.h:66
Definition: fs_annot.h:51
Definition: fs_annot.h:5023
WIDE STRING CLASS.
Definition: fx_string.h:1452
Form & operator=(const Form &other)
Assign operator.
void SetDefaultAppearance(const DefaultAppearance &default_ap)
Set default appearance data.
Definition: fs_pdfdoc.h:508
Definition: fs_pdfform.h:687
Definition: fs_pdfform.h:1239
bool RenameField(Field &field, const wchar_t *new_field_name)
Rename a field with a new name.
void FixPageFields(int page_index)
Fix the fields which are in a PDF page but cannot be counted by current form object.
bool operator==(const char *str1, const CFX_ByteString &str2)
Check if two byte strings are equal.
Definition: fs_basictypes.h:128
bool Reset()
Reset data of all fields (except signature fields) to their default value.
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.
void SetDefaultAppearance(const DefaultAppearance &default_ap)
Set default appearance data.
void RemoveField(Field &field)
Remove a form field. (Not support signature field)
void SetFieldsInCalculationOrder(const FieldArray &field_array)
Set an array of form fields in calculation order.
Control & operator=(const Control &other)
Assign operator.
WString GetExportValue() const
Get export mapping name when related form field is check box or radio button.
File stream interface, reading & writing.
Definition: fx_stream.h:669
bool NeedConstructAppearances() const
Check whether to construct appearance when loading form controls.
WString option_value
The option string value.
Definition: fs_pdfform.h:117
ChoiceOption()
Constructor.
Definition: fs_pdfform.h:50
bool operator !=(const Form &other) const
Not equal operator.
bool IsChecked() const
Check if the current form control is checked when related form field is check box or radio button.
FieldArray GetFieldsInCalculationOrder()
Get an array of form fields in calculation order.
Field GetField() const
Get the related form field.
Definition: fs_pdfform.h:145
bool operator==(const Form &other) const
Equal operator.
bool ImportFromXML(const char *file_path)
Import the form data from an XML file.
FX_UINT32 uint32
32-bit unsigned integer.
Definition: fs_basictypes.h:196
Definition: fs_pdfpage.h:411
void SetConstructAppearances(bool need_construct)
Set a flag that specifies whether to construct appearances when loading form controls.
void * FS_HANDLE
Handle type.
Definition: fs_basictypes.h:214
bool selected
Used to indicate whether the option is selected or not.
Definition: fs_pdfform.h:123
Header file for common definitions and classes.
void SetAlignment(common::Alignment alignment)
Set alignment value which is used as document-wide default value.
bool IsEmpty() const
Check whether current object is empty or not.
bool ExportToCSV(const wchar_t *csv_file_path, const wchar_t *pdf_file_name, bool is_append)
Export the form data to a CSV file.
Alignment
Enumeration for alignment (horizontal).
Definition: fs_common.h:75
Header file for PDF object related definitions and classes.
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,...
Definition: fs_basictypes.h:407
DefaultAppearance GetDefaultAppearance() const
Get the default appearance data.
annots::Widget GetWidget() const
Get the related widget annotation.
bool operator !=(const Control &other) const
Not equal operator.
Definition: fs_pdfobject.h:800
ChoiceOption(const ChoiceOption &option)
Constructor, with another choice option object.
Definition: fs_pdfform.h:77
bool ExportToXML(const char *file_path)
Export the form data to an XML file.
Foxit namespace.
Definition: fs_taggedpdf.h:27
Definition: fs_pdfobject.h:55
Type
Enumeration for form field type.
Definition: fs_pdfform.h:152
WString option_label
The displayed string value for the option.
Definition: fs_pdfform.h:120
Definition: fs_pdfform.h:47
Definition: fs_pdfform.h:44
common::Alignment GetAlignment()
Get the alignment value.
void RemoveControl(Control &control)
Remove a form control. (Not support to remove a form control from a signature field)
Form(const pdf::PDFDoc &document)
Constructor, with PDF document.
objects::PDFDictionary * GetDict() const
Get the dictionary of current object.
#define NULL
The null-pointer value.
Definition: fx_system.h:780
PDFDoc GetDocument() const
Get the PDF document, with which current form object is associated.
int GetFieldCount(const wchar_t *filter=0) const
Get the count of form fields, whose names satisfy the specified name filter.
bool ExportToTXT(const wchar_t *txt_file_path, const FieldArray &field_array, bool is_include)
Export data of specified form fields to a TXT file.
Definition: fx_coordinates.h:1076
bool operator==(const Control &other) const
Equal operator.
Control(const Control &other)
Constructor, with another form control object.
bool MoveControl(Control &control, const wchar_t *field_name)
Move the control to a field specified by field name.
Definition: fs_pdfform.h:130
Field GetField(int index, const wchar_t *filter=0)
Get a form field by index, whose names satisfy the specified name filter.
void SetAlignment(common::Alignment alignment)
Set alignment property of current form control.
int GetControlCount(const PDFPage &page) const
Get count of form controls in a specified PDF page.
Definition: fx_coordinates.h:771
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.