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 
351  WString GetDefaultValue() const;
352 
363  void SetDefaultValue(const wchar_t* value);
364 
375  WString GetValue() const;
376 
402  void SetValue(const wchar_t* value);
403 
416  common::Alignment GetAlignment() const;
417 
434  void SetAlignment(common::Alignment alignment);
435 
446  WString GetAlternateName() const;
447 
461  void SetAlternateName(const wchar_t* alternate_name);
462 
468  DefaultAppearance GetDefaultAppearance() const;
469 
481  void SetDefaultAppearance(const DefaultAppearance& default_ap);
482 
490  WString GetMappingName() const;
491 
502  void SetMappingName(const wchar_t* name);
503 
511  int GetMaxLength() const;
512 
522  void SetMaxLength(int max_length);
523 
532  ChoiceOptionArray GetOptions() const;
533 
544  void SetOptions(const ChoiceOptionArray& option_array);
545 
555  int GetTopVisibleIndex();
556 
568  void SetTopVisibleIndex(int index);
569 
575  int GetControlCount() const;
576 
585  Control GetControl(int index);
586 
594  int GetControlCount(const foxit::pdf::PDFPage& page) const;
595 
606  Control GetControl(const foxit::pdf::PDFPage& page, int index);
607 
613  bool Reset();
614 
620  objects::PDFDictionary* GetDict() const;
621 
630  objects::PDFObject* GetValueObj() const;
631 
640  objects::PDFObject* GetDefaultValueObj() const;
641 
653  objects::PDFObject* GetInheritedAttribute(const char* attribute_name) const;
654 
655  // User is strongly recommended NOT to use this method; otherwise unknown situation may occur.
656  explicit Field(FS_HANDLE handle = NULL);
657 };
658 
684 class Form FS_FINAL : public Base {
685  public:
694  explicit Form(const pdf::PDFDoc& document);
700  Form(const Form& other);
708  Form& operator = (const Form& other);
709 
717  bool operator == (const Form& other) const;
725  bool operator != (const Form& other) const;
726 
728  ~Form();
729 
737  bool IsEmpty() const;
738 
751 
766  void SetAlignment(common::Alignment alignment);
767 
773  bool NeedConstructAppearances() const;
774 
783  void SetConstructAppearances(bool need_construct);
784 
803  Control GetControlAtDevicePoint(const PDFPage& page, const PointF& point, float tolerance, Field::Type type,
804  const Matrix* matrix = NULL);
805 
820  Control GetControlAtPoint(const PDFPage& page, const PointF& point, float tolerance, Field::Type type);
821 
828 
840  void SetDefaultAppearance(const DefaultAppearance& default_ap);
841 
847  PDFDoc GetDocument() const;
848 
858 
869  void SetFieldsInCalculationOrder(const FieldArray& field_array);
870 
883  bool ValidateFieldName(Field::Type type, const WString& field_name);
884 
893  bool RenameField(Field& field, const wchar_t* new_field_name);
894 
941  Control AddControl(const PDFPage& page, const wchar_t* field_name, Field::Type field_type, const RectF& rect);
942 
962  bool MoveControl(Control& control, const wchar_t* field_name);
963 
976  void RemoveField(Field& field);
977 
989  void RemoveControl(Control& control);
990 
1003  int GetFieldCount(const wchar_t* filter = NULL) const;
1004 
1020  Field GetField(int index, const wchar_t* filter = NULL);
1021 
1029  int GetControlCount(const PDFPage& page) const;
1030 
1041  Control GetControl(const PDFPage& page, int index);
1042 
1043 #ifndef _FX_NO_JSE_
1044 
1051  Filler GetFormFiller() const;
1052 #endif // #ifndef _FX_NO_JSE_
1053 
1059  bool Reset();
1060 
1069  bool ExportToXML(const char* file_path);
1070 
1083  bool ExportToXML(const wchar_t* file_path, const FieldArray& field_array, bool is_include);
1084 
1098  bool ExportToXML(foxit::common::file::WriterCallback* xml_file, const FieldArray& field_array, bool is_include);
1099 
1108  bool ImportFromXML(const char* file_path);
1109 
1122  bool ExportToCSV(const wchar_t* csv_file_path, const wchar_t* pdf_file_name, bool is_append);
1123 
1136  bool ExportToCSV(foxit::common::file::StreamCallback* csv_file, const wchar_t* pdf_file_name, bool is_append);
1137 
1151  bool ExportToHTML(const wchar_t* html_file_path, const FieldArray& field_array, bool is_include);
1152 
1166  bool ExportToHTML(foxit::common::file::WriterCallback* html_file, const FieldArray& field_array, bool is_include);
1167 
1181  bool ExportToTXT(const wchar_t* txt_file_path, const FieldArray& field_array, bool is_include);
1182 
1196  bool ExportToTXT(foxit::common::file::WriterCallback* txt_file, const FieldArray& field_array, bool is_include);
1197 
1204 
1215  void FixPageFields(int page_index);
1216 
1217  // User is strongly recommended NOT to use this method; otherwise unknown situation may occur.
1218  explicit Form(FS_HANDLE handle = NULL);
1219 };
1220 
1236 class Control FS_FINAL : public Base {
1237  public:
1243  Control(const Control& other);
1251  Control& operator = (const Control& other);
1252 
1260  bool operator == (const Control& other) const;
1268  bool operator != (const Control& other) const;
1269 
1271  ~Control();
1272 
1280  bool IsEmpty() const;
1281 
1287  Field GetField() const;
1288 
1295 
1301  annots::Widget GetWidget() const;
1302 
1308  int GetIndex() const;
1309 
1318  WString GetExportValue() const;
1319 
1330  void SetExportValue(const wchar_t* value);
1331 
1340  bool IsChecked() const;
1341 
1352  void SetChecked(bool checked_status);
1353 
1363  bool IsDefaultChecked() const;
1364 
1375  void SetDefaultChecked(bool checked_status);
1376 
1383 
1395  void SetDefaultAppearance(const DefaultAppearance& default_ap);
1396 
1410 
1426  void SetAlignment(common::Alignment alignment);
1427 
1428  // User is strongly recommended NOT to use this method; otherwise unknown situation may occur.
1429  explicit Control(FS_HANDLE handle = NULL);
1430 
1431 };
1432 } // namespace interform
1433 } // namespace pdf
1434 } // namespace foxit
1435 #endif // FS_PDFFORM_H_
1436 
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:453
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:221
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:50
Definition: fs_annot.h:5172
WIDE STRING CLASS.
Definition: fx_string.h:1461
Form & operator=(const Form &other)
Assign operator.
void SetDefaultAppearance(const DefaultAppearance &default_ap)
Set default appearance data.
Definition: fs_pdfdoc.h:648
Definition: fs_pdfform.h:684
Definition: fs_pdfform.h:1236
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:675
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:412
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:94
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:443
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:809
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:792
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.