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 
foxit::pdf::interform::Form::RemoveControl
void RemoveControl(Control &control)
Remove a form control. (Not support to remove a form control from a signature field)
foxit::pdf::interform::Form::operator=
Form & operator=(const Form &other)
Assign operator.
foxit::pdf::interform::Control
Definition: fs_pdfform.h:1236
IFX_FileWrite
File writing interface.
Definition: fx_stream.h:453
foxit::FS_HANDLE
void * FS_HANDLE
Handle type.
Definition: fs_basictypes.h:214
foxit::pdf::interform::Form::Reset
bool Reset()
Reset data of all fields (except signature fields) to their default value.
foxit::pdf::interform::FieldArray
Definition: fs_pdfform.h:44
foxit::pdf::interform::Form::SetConstructAppearances
void SetConstructAppearances(bool need_construct)
Set a flag that specifies whether to construct appearances when loading form controls.
foxit::pdf::interform::ChoiceOption::ChoiceOption
ChoiceOption(const ChoiceOption &option)
Constructor, with another choice option object.
Definition: fs_pdfform.h:77
foxit::pdf::interform::Form::RenameField
bool RenameField(Field &field, const wchar_t *new_field_name)
Rename a field with a new name.
foxit::pdf::interform::Form::MoveControl
bool MoveControl(Control &control, const wchar_t *field_name)
Move the control to a field specified by field name.
foxit::pdf::interform::Control::IsEmpty
bool IsEmpty() const
Check whether current object is empty or not.
foxit::pdf::interform::Control::GetAlignment
common::Alignment GetAlignment()
Get the alignment value.
foxit::pdf::interform::Form::operator==
bool operator==(const Form &other) const
Equal operator.
foxit::Object
CFX_Object Object
Object type.
Definition: fs_basictypes.h:221
foxit::pdf::interform::Control::GetExportValue
WString GetExportValue() const
Get export mapping name when related form field is check box or radio button.
foxit::pdf::interform::Control::GetWidget
annots::Widget GetWidget() const
Get the related widget annotation.
foxit::pdf::interform::Form::RemoveField
void RemoveField(Field &field)
Remove a form field. (Not support signature field)
IFX_FileStream
File stream interface, reading & writing.
Definition: fx_stream.h:675
foxit::pdf::interform::Control::IsDefaultChecked
bool IsDefaultChecked() const
Check if the current form control is checked by default when related form field is check box or radio...
fs_common.h
Header file for common definitions and classes.
foxit::pdf::interform::Form::GetDefaultAppearance
DefaultAppearance GetDefaultAppearance() const
Get the default appearance data.
foxit::pdf::interform::Form::IsEmpty
bool IsEmpty() const
Check whether current object is empty or not.
foxit::pdf::interform::Form::ValidateFieldName
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.
foxit::pdf::interform::Form::NeedConstructAppearances
bool NeedConstructAppearances() const
Check whether to construct appearance when loading form controls.
foxit::common::Alignment
Alignment
Enumeration for alignment (horizontal).
Definition: fs_common.h:75
foxit::pdf::interform::ChoiceOption::selected
bool selected
Used to indicate whether the option is selected or not.
Definition: fs_pdfform.h:123
foxit::pdf::interform::ChoiceOption::default_selected
bool default_selected
Used to indicate whether the option would be selected by default or not.
Definition: fs_pdfform.h:126
foxit::pdf::annots::Widget
Definition: fs_annot.h:5127
foxit::pdf::interform::Control::GetField
Field GetField() const
Get the related form field.
foxit::pdf::interform::ChoiceOption::Set
void Set(const wchar_t *option_value, const wchar_t *option_label, bool selected, bool default_selected)
Set value.
Definition: fs_pdfform.h:110
foxit::pdf::interform::Form::GetControl
Control GetControl(const PDFPage &page, int index)
Get a form control by index, in a specified PDF page.
foxit::pdf::interform::ChoiceOption::option_label
WString option_label
The displayed string value for the option.
Definition: fs_pdfform.h:120
foxit::pdf::objects::PDFObject
Definition: fs_pdfobject.h:55
foxit::pdf::interform::Form::GetField
Field GetField(int index, const wchar_t *filter=0)
Get a form field by index, whose names satisfy the specified name filter.
foxit::pdf::interform::Form::GetFieldCount
int GetFieldCount(const wchar_t *filter=0) const
Get the count of form fields, whose names satisfy the specified name filter.
foxit::pdf::interform::Control::~Control
~Control()
Destructor.
foxit::pdf::interform::Control::operator=
Control & operator=(const Control &other)
Assign operator.
foxit::pdf::interform::Control::operator==
bool operator==(const Control &other) const
Equal operator.
foxit::pdf::interform::Form::ExportToXML
bool ExportToXML(const char *file_path)
Export the form data to an XML file.
foxit::pdf::interform::Form::AddControl
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,...
foxit::pdf::interform::Form::ExportToTXT
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.
foxit::pdf::interform::Field
Definition: fs_pdfform.h:145
foxit::pdf::interform::Form::SetAlignment
void SetAlignment(common::Alignment alignment)
Set alignment value which is used as document-wide default value.
foxit::pdf::interform::Form::GetAlignment
common::Alignment GetAlignment() const
Get the alignment value which is used as document-wide default value.
foxit::pdf::interform::Form::SetDefaultAppearance
void SetDefaultAppearance(const DefaultAppearance &default_ap)
Set default appearance data.
foxit::pdf::interform::Form::~Form
~Form()
Destructor.
fs_formfiller.h
Header file for form filler related definitions and classes.
CFX_PSVTemplate
Definition: fx_coordinates.h:30
foxit::pdf::interform::Control::GetWidgetDict
objects::PDFDictionary * GetWidgetDict() const
Get the dictionary of related widget annotation.
foxit::pdf::interform::Form::GetControlAtDevicePoint
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.
foxit::pdf::interform::Form::GetFormFiller
Filler GetFormFiller() const
Get the form filler.
operator==
bool operator==(const char *str1, const CFX_ByteString &str2)
Check if two byte strings are equal.
Definition: fs_basictypes.h:128
foxit::pdf::interform::Control::GetDefaultAppearance
DefaultAppearance GetDefaultAppearance() const
Get the default appearance data.
fs_pdfobject.h
Header file for PDF object related definitions and classes.
foxit::pdf::interform::Control::SetExportValue
void SetExportValue(const wchar_t *value)
Set export mapping name when related form field is check box or radio button.
foxit::pdf::interform::Form::GetControlAtPoint
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.
foxit
Foxit namespace.
Definition: fs_taggedpdf.h:27
foxit::pdf::interform::Field::Type
Type
Enumeration for form field type.
Definition: fs_pdfform.h:152
foxit::pdf::interform::ChoiceOption::option_value
WString option_value
The option string value.
Definition: fs_pdfform.h:117
foxit::pdf::interform::Form::FixPageFields
void FixPageFields(int page_index)
Fix the fields which are in a PDF page but cannot be counted by current form object.
foxit::pdf::interform::ChoiceOption::ChoiceOption
ChoiceOption(const wchar_t *option_value, const wchar_t *option_label, bool selected, bool default_selected)
Constructor, with parameters.
Definition: fs_pdfform.h:66
foxit::pdf::objects::PDFDictionary
Definition: fs_pdfobject.h:809
operator!=
bool operator!=(const char *str1, const CFX_ByteString &str2)
Check if two byte strings are not equal.
Definition: fs_basictypes.h:140
foxit::pdf::interform::Control::SetDefaultChecked
void SetDefaultChecked(bool checked_status)
Set the default check state of current form control when related form field is check box or radio but...
foxit::pdf::interform::Control::Control
Control(const Control &other)
Constructor, with another form control object.
foxit::pdf::interform::Filler
Definition: fs_formfiller.h:271
foxit::pdf::interform::Form::GetDict
objects::PDFDictionary * GetDict() const
Get the dictionary of current object.
fs_fdfdoc.h
Header file for FDF doucument related definitions and classes.
foxit::pdf::interform::Control::operator!=
bool operator!=(const Control &other) const
Not equal operator.
foxit::pdf::interform::Control::IsChecked
bool IsChecked() const
Check if the current form control is checked when related form field is check box or radio button.
foxit::pdf::interform::Form::GetDocument
PDFDoc GetDocument() const
Get the PDF document, with which current form object is associated.
foxit::pdf::interform::Form::SetFieldsInCalculationOrder
void SetFieldsInCalculationOrder(const FieldArray &field_array)
Set an array of form fields in calculation order.
foxit::pdf::interform::Form::GetControlCount
int GetControlCount(const PDFPage &page) const
Get count of form controls in a specified PDF page.
NULL
#define NULL
The null-pointer value.
Definition: fx_system.h:780
CFX_FloatRect
Definition: fx_coordinates.h:771
foxit::pdf::interform::Form::ExportToHTML
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.
foxit::pdf::interform::Form::GetFieldsInCalculationOrder
FieldArray GetFieldsInCalculationOrder()
Get an array of form fields in calculation order.
foxit::pdf::PDFDoc
Definition: fs_pdfdoc.h:610
foxit::pdf::PDFPage
Definition: fs_pdfpage.h:412
foxit::pdf::interform::Control::GetIndex
int GetIndex() const
Get the index of current form control among all the controls of related form field.
foxit::pdf::interform::Form::ExportToCSV
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.
CFX_Matrix
Definition: fx_coordinates.h:1076
foxit::pdf::interform::ChoiceOption
Definition: fs_pdfform.h:47
foxit::pdf::DefaultAppearance
Definition: fs_annot.h:52
foxit::pdf::interform::ChoiceOptionArray
Definition: fs_pdfform.h:130
CFX_WideString
WIDE STRING CLASS.
Definition: fx_string.h:1452
foxit::pdf::interform::Control::SetChecked
void SetChecked(bool checked_status)
Set the check state of current form control when related form field is check box or radio button.
foxit::pdf::interform::Control::SetAlignment
void SetAlignment(common::Alignment alignment)
Set alignment property of current form control.
foxit::pdf::interform::Control::SetDefaultAppearance
void SetDefaultAppearance(const DefaultAppearance &default_ap)
Set default appearance data.
foxit::pdf::interform::ChoiceOption::ChoiceOption
ChoiceOption()
Constructor.
Definition: fs_pdfform.h:50
foxit::uint32
FX_UINT32 uint32
32-bit unsigned integer.
Definition: fs_basictypes.h:196
foxit::pdf::interform::Form::ImportFromXML
bool ImportFromXML(const char *file_path)
Import the form data from an XML file.
foxit::pdf::interform::Form::operator!=
bool operator!=(const Form &other) const
Not equal operator.
foxit::Base
Definition: fs_basictypes.h:427
foxit::pdf::interform::Form
Definition: fs_pdfform.h:684
foxit::pdf::interform::Form::Form
Form(const pdf::PDFDoc &document)
Constructor, with PDF document.