Foxit PDF SDK
foxit::pdf::interform::Field Class Reference
Inheritance diagram for foxit::pdf::interform::Field:
foxit::Base foxit::pdf::Signature

Public Types

enum  Flags {
  e_FlagReadOnly = 0x01, e_FlagRequired = 0x02, e_FlagNoExport = 0x04, e_FlagButtonNoToggleToOff = 0x100,
  e_FlagButtonRadiosInUnison = 0x200, e_FlagTextMultiline = 0x100, e_FlagTextPassword = 0x200, e_FlagTextDoNotScroll = 0x400,
  e_FlagTextComb = 0x800, e_FlagComboEdit = 0x100, e_FlagChoiseMultiSelect = 0x100
}
 Enumeration for form field flags. More...
 
enum  Type {
  e_TypeUnknown = 0, e_TypePushButton = 1, e_TypeCheckBox = 2, e_TypeRadioButton = 3,
  e_TypeComboBox = 4, e_TypeListBox = 5, e_TypeTextField = 6, e_TypeSignature = 7
}
 Enumeration for form field type. More...
 

Public Member Functions

 Field (const PDFDoc &document, objects::PDFDictionary *field_dict)
 Constructor, from field dictionary. More...
 
 Field (const Field &field)
 Constructor, with another form field object. More...
 
 ~Field ()
 Destructor.
 
common::Alignment GetAlignment () const
 Get the alignment value. More...
 
WString GetAlternateName () const
 Get alternate name. More...
 
Control GetControl (int index)
 Get a form control by index. More...
 
Control GetControl (const foxit::pdf::PDFPage &page, int index)
 Get a form control by index, in a specified PDF page. More...
 
int GetControlCount () const
 Get count of form controls. More...
 
int GetControlCount (const foxit::pdf::PDFPage &page) const
 Get count of form controls in a specified PDF page. More...
 
DefaultAppearance GetDefaultAppearance () const
 Get the default appearance data. More...
 
WString GetDefaultValue () const
 Get default value. More...
 
objects::PDFObjectGetDefaultValueObj () const
 Get the PDF object of field's default value. More...
 
objects::PDFDictionaryGetDict () const
 Get the PDF dictionary of current object. More...
 
uint32 GetFlags () const
 Get field flags. More...
 
objects::PDFObjectGetInheritedAttribute (const char *attribute_name) const
 Get the PDF object for specified attribute which may be inherited from the ancestor node in the field tree. More...
 
WString GetMappingName () const
 Get mapping name. More...
 
int GetMaxLength () const
 Get maximum length of the field's text, in characters. More...
 
WString GetName () const
 Get field name. More...
 
ChoiceOptionArray GetOptions () const
 Get options of list box or combo box. More...
 
int GetTopVisibleIndex ()
 Get top index of option for scrollable list boxes. More...
 
Type GetType () const
 Get field type. More...
 
WString GetValue () const
 Get value. More...
 
objects::PDFObjectGetValueObj () const
 Get the PDF object of field's value. More...
 
bool IsEmpty () const
 Check whether current object is empty or not. More...
 
bool operator!= (const Field &other) const
 Not equal operator. More...
 
Fieldoperator= (const Field &other)
 Assign operator. More...
 
bool operator== (const Field &other) const
 Equal operator. More...
 
bool Reset ()
 Reset data in current field to its default value. (Not support signature field) More...
 
void SetAlignment (common::Alignment alignment)
 Set alignment property of a form, as a document-wide default value. (Not support signature field) More...
 
void SetAlternateName (const wchar_t *alternate_name)
 Set alternate name. (Not support signature field) More...
 
void SetDefaultAppearance (const DefaultAppearance &default_ap)
 Set default appearance data. More...
 
void SetDefaultValue (const wchar_t *value)
 Set default value. More...
 
void SetFlags (uint32 flags)
 Set field flags. More...
 
void SetMappingName (const wchar_t *name)
 Set mapping name. (Not support signature field) More...
 
void SetMaxLength (int max_length)
 Set maximum length of the field's text, in characters. More...
 
void SetOptions (const ChoiceOptionArray &option_array)
 Set options of list box or combo box. More...
 
void SetTopVisibleIndex (int index)
 Set top index for scrollable list boxes. More...
 
void SetValue (const wchar_t *value)
 Set value. More...
 
- Public Member Functions inherited from foxit::Base
FS_HANDLE Handle () const
 Get the handle of current object. More...
 

Detailed Description

In a PDF document, form fields appear on any combination of pages and all of them make up a single, global interactive form spanning the entire document. Function Form::GetField can use to get a form field from interactive form. This class offers functions to get some information/properties of a form field, reset the form field to its default value, and get form control from form field.
When a form fiels's type is Field::e_TypeSignature, the form field object is a signature object in fact.
To access additional actions, please construct an actions::AdditionalAction object with Field object.

See also
Form
pdf::Signature
actions::AdditionalAction

Member Enumeration Documentation

◆ Flags

Enumeration for form field flags.

Values of this enumeration can be used alone or in a combination.

Enumerator
e_FlagReadOnly 

If set, the user may not change the value of the field. Any associated widget annotations will not interact with the user; that is, they will not respond to mouse clicks or change their appearance in response to mouse motions. This flag is useful for fields whose values are computed or imported from a database.

e_FlagRequired 

If set, the field must have a value at the time it is exported by a submit-form action.

e_FlagNoExport 

if set, the field must not be exported by a submit-form action.

e_FlagButtonNoToggleToOff 

(Only useful for radio button) If set, exactly one radio button must be selected at all times; clicking the currently selected button has no effect. If clear, clicking the selected button deselects it, leaving no button selected.

e_FlagButtonRadiosInUnison 

(Only useful for radio button) If set, a group of radio buttons within a radio button field that use the same value for the on state will turn on and off in unison; that is if one is checked, they are all checked. If clear, the buttons are mutually exclusive.

e_FlagTextMultiline 

(Only useful for text field) If set, the text field can contain multiple lines of text; if clear, the field's text is restricted to a single line.

e_FlagTextPassword 

(Only useful for text field) If set, the field is intended for entering a secure password that should not be echoed visibly to the screen. Characters typed from the keyboard should instead be echoed in some unreadable form, such as asterisks or bullet characters.

Note
To protect password confidentiality, viewer applications should never store the value of the text field in the PDF file if this flag is set.
e_FlagTextDoNotScroll 

(Only useful for text field) If set, the field does not scroll (horizontally for single-line fields, vertically for multiple-line fields) to accommodate more text than fits within its annotation rectangle. Once the field is full, no further text is accepted.

e_FlagTextComb 

(Only useful for text field) If set, use combs.

If set, the field is automatically divided into as many equally spaced positions, or combs, as the value of maximum length of a field's text, and the text is laid out into those combs.

e_FlagComboEdit 

(Only useful for combo box) If set, the combo box includes an editable text control with a drop-down list, if clear, it includes only a drop-down list.

e_FlagChoiseMultiSelect 

(Only useful for combo box and list box) If set, more than one items may be selected simultaneously; if clear, no more than one item at a time may be selected.

◆ Type

Enumeration for form field type.

Values of this enumeration should be used alone.

Enumerator
e_TypeUnknown 

Form field type: unknown.

e_TypePushButton 

Form field type: push button.

e_TypeCheckBox 

Form field type: check box.

e_TypeRadioButton 

Form field type: radio button.

e_TypeComboBox 

Form field type: combo box.

e_TypeListBox 

Form field type: list box.

e_TypeTextField 

Form field type: text field.

e_TypeSignature 

Form field type: signature field.

Constructor & Destructor Documentation

◆ Field() [1/2]

foxit::pdf::interform::Field::Field ( const PDFDoc document,
objects::PDFDictionary field_dict 
)

Constructor, from field dictionary.

Parameters
[in]documentA valid PDF document.
[in]field_dictA PDF dictionary which represents a form field. It should belong to the PDF document specified by parameter document;

◆ Field() [2/2]

foxit::pdf::interform::Field::Field ( const Field field)

Constructor, with another form field object.

Parameters
[in]fieldAnother form field object.

Member Function Documentation

◆ GetAlignment()

common::Alignment foxit::pdf::interform::Field::GetAlignment ( ) const

Get the alignment value.

Alignment is a property for variable text and it is only useful 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 alignment value will be used for the text field or list box.

Returns
The alignment value. Please refer to values starting from common::e_AlignmentLeft and this would be one of these values.

◆ GetAlternateName()

WString foxit::pdf::interform::Field::GetAlternateName ( ) const

Get alternate name.

An alternate field name to be used in place of the actual field name wherever the field must be identified in the user interface (such as in error or status messages referring to the field). This text is also useful when extracting the document's contents in support of accessibility to users with disabilities or for other purposes.

Returns
The alternate name.

◆ GetControl() [1/2]

Control foxit::pdf::interform::Field::GetControl ( int  index)

Get a form control by index.

Parameters
[in]indexForm control index. Valid range: from 0 to (count-1). count is returned by function Field::GetControlCount.
Returns
A form control object.

◆ GetControl() [2/2]

Control foxit::pdf::interform::Field::GetControl ( const foxit::pdf::PDFPage page,
int  index 
)

Get a form control by index, in a specified PDF page.

Parameters
[in]pageA valid PDF page object. It should be in the same document as current form field.
[in]indexForm control index. Valid range: from 0 to (count-1). count is returned by function Field::GetControlCount with same parameter page.
Returns
form control object.

◆ GetControlCount() [1/2]

int foxit::pdf::interform::Field::GetControlCount ( ) const

Get count of form controls.

Returns
The count of the form controls.

◆ GetControlCount() [2/2]

int foxit::pdf::interform::Field::GetControlCount ( const foxit::pdf::PDFPage page) const

Get count of form controls in a specified PDF page.

Parameters
[in]pageA valid PDF page object. It should be in the same document as current form field.
Returns
The count of the form controls in the specified PDF page.

◆ GetDefaultAppearance()

DefaultAppearance foxit::pdf::interform::Field::GetDefaultAppearance ( ) const

Get the default appearance data.

Returns
The default appearance data.

◆ GetDefaultValue()

WString foxit::pdf::interform::Field::GetDefaultValue ( ) const

Get default value.

Applicable for all fields except push button. For field types that are not applicable, an empty string will be returned.

Returns
Default value string.

◆ GetDefaultValueObj()

objects::PDFObject* foxit::pdf::interform::Field::GetDefaultValueObj ( ) const

Get the PDF object of field's default value.

The format of field's default value varies depending on the field type. For more details, please refer to "TABLE 8.69 Entries common to all field dictionaries" in <PDF reference 1.7> P676.

Returns
A PDF object.

◆ GetDict()

objects::PDFDictionary* foxit::pdf::interform::Field::GetDict ( ) const

Get the PDF dictionary of current object.

Returns
The PDF dictionary of current object.

◆ GetFlags()

uint32 foxit::pdf::interform::Field::GetFlags ( ) const

Get field flags.

Field flags specifies various characteristics of a form field.

Returns
Form field flags. Please refer to values starting from Field::e_FlagReadOnly and this would be one or a combination of these values.

◆ GetInheritedAttribute()

objects::PDFObject* foxit::pdf::interform::Field::GetInheritedAttribute ( const char *  attribute_name) const

Get the PDF object for specified attribute which may be inherited from the ancestor node in the field tree.

Some of the field attributes are designated as inheritable, such as "Ff", "V", "DV", and so on. Please refer to "TABLE 8.69 Entries common to all field dictionaries" in <PDF Reference 1.7> P675.

Parameters
[in]attribute_nameThe name of attribute to be found.
Returns
A PDF object. If not found, this function will return NULL.

◆ GetMappingName()

WString foxit::pdf::interform::Field::GetMappingName ( ) const

Get mapping name.

Mapping name is to be used when exporting interactive form field data from the document.

Returns
The mapping name.

◆ GetMaxLength()

int foxit::pdf::interform::Field::GetMaxLength ( ) const

Get maximum length of the field's text, in characters.

Applicable for text fields. For field types that are not applicable, this function will return 0.

Returns
The maximum length of the field's text.

◆ GetName()

WString foxit::pdf::interform::Field::GetName ( ) const

Get field name.

Returns
Field name string.

◆ GetOptions()

ChoiceOptionArray foxit::pdf::interform::Field::GetOptions ( ) const

Get options of list box or combo box.

Applicable for list box and combo box. For field types that are not applicable, this function will return an empty array.

Returns
An array that contains the options.

◆ GetTopVisibleIndex()

int foxit::pdf::interform::Field::GetTopVisibleIndex ( )

Get top index of option for scrollable list boxes.

Applicable for list box. For field types that are not applicable, this function will return 0.
Top index of option is the the index of the first option visible in the list.

Returns
The index of first item which is in visible scope of list box.

◆ GetType()

Type foxit::pdf::interform::Field::GetType ( ) const

Get field type.

Returns
Form field type. Please refer to values starting from Field::e_TypeUnknown and this would be one of these values.

◆ GetValue()

WString foxit::pdf::interform::Field::GetValue ( ) const

Get value.

Applicable for all fields except push button. For field types that are not applicable, an empty string will be returned.

Returns
Value string. Specially, when current field is a list box field with multiple values, only the first value would be returned.

◆ GetValueObj()

objects::PDFObject* foxit::pdf::interform::Field::GetValueObj ( ) const

Get the PDF object of field's value.

The format of field's value varies depending on the field type. For more details, please refer to "TABLE 8.69 Entries common to all field dictionaries" in <PDF reference 1.7> P676.

Returns
A PDF object.

◆ IsEmpty()

bool foxit::pdf::interform::Field::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.

◆ operator!=()

bool foxit::pdf::interform::Field::operator!= ( const Field other) const

Not equal operator.

Parameters
[in]otherAnother form field object. This function will check if current object is not equal to this one.
Returns
true means not equal, while false means equal.

◆ operator=()

Field& foxit::pdf::interform::Field::operator= ( const Field other)

Assign operator.

Parameters
[in]otherAnother form field object, whose value would be assigned to current object.
Returns
Reference to current object itself.

◆ operator==()

bool foxit::pdf::interform::Field::operator== ( const Field other) const

Equal operator.

Parameters
[in]otherAnother form field object. This function will check if current object is equal to this one.
Returns
true means equal, while false means not equal.

◆ Reset()

bool foxit::pdf::interform::Field::Reset ( )

Reset data in current field to its default value. (Not support signature field)

Returns
true means success, while false means current form field is a signature field or failure.

◆ SetAlignment()

void foxit::pdf::interform::Field::SetAlignment ( common::Alignment  alignment)

Set alignment property of a form, as a document-wide default value. (Not support signature field)

Alignment is a property for variable text and it is only useful 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 alignment value will be used for the text field or list box.
If current form field is a signature field, this function will do nothing.

Parameters
[in]alignmentThe 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.
Returns
None.

◆ SetAlternateName()

void foxit::pdf::interform::Field::SetAlternateName ( const wchar_t *  alternate_name)

Set alternate name. (Not support signature field)

An alternate field name is to be used in place of the actual field name wherever the field must be identified in the user interface (such as in error or status messages referring to the field). This text is also useful when extracting the document's contents in support of accessibility to users with disabilities or for other purposes.
If current form field is a signature field, this function will do nothing.

Parameters
[in]alternate_nameA new alternate name string. It should not be an empty string.
Returns
None.

◆ SetDefaultAppearance()

void foxit::pdf::interform::Field::SetDefaultAppearance ( const DefaultAppearance default_ap)

Set default appearance data.

Parameters
[in]default_apThe 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.
Returns
None.

◆ SetDefaultValue()

void foxit::pdf::interform::Field::SetDefaultValue ( const wchar_t *  value)

Set default value.

Applicable for all fields except push button. For field types that are not applicable, this function will do nothing.

Parameters
[in]valueNew default value string. It should not be an empty string.
Returns
None.

◆ SetFlags()

void foxit::pdf::interform::Field::SetFlags ( uint32  flags)

Set field flags.

Field flags specifies various characteristics of a form field.

Parameters
[in]flagsNew form field flags. Please refer to values starting from Field::e_FlagReadOnly and this should be one or a combination of these values.
Returns
None.

◆ SetMappingName()

void foxit::pdf::interform::Field::SetMappingName ( const wchar_t *  name)

Set mapping name. (Not support signature field)

Mapping name is to be used when exporting interactive form field data from the document. If current form field is a signature field, this function will do nothing.

Parameters
[in]nameNew mapping name string.It should not be an empty string.
Returns
None.

◆ SetMaxLength()

void foxit::pdf::interform::Field::SetMaxLength ( int  max_length)

Set maximum length of the field's text, in characters.

Applicable for text fields. For field types that are not applicable, this function will do nothing.

Parameters
[in]max_lengthNew maximum length of the field's text. It should be non-negative.
Returns
None.

◆ SetOptions()

void foxit::pdf::interform::Field::SetOptions ( const ChoiceOptionArray option_array)

Set options of list box or combo box.

Applicable for list box and combo box. For field types that are not applicable, this function will do nothing.

Parameters
[in]option_arrayAn array of options which is to be set to list box or combo box.
Returns
None.

◆ SetTopVisibleIndex()

void foxit::pdf::interform::Field::SetTopVisibleIndex ( int  index)

Set top index for scrollable list boxes.

Applicable for list box. For field types that are not applicable, this function will do nothing.
Top index of option is the the index of the first option visible in the list.

Parameters
[in]indexThe index of the first option visible in the list.
Returns
None.

◆ SetValue()

void foxit::pdf::interform::Field::SetValue ( const wchar_t *  value)

Set value.

Applicable for all fields except push button. For field types that are not applicable, this function will do nothing.
Specially, for combo box and text field, when setting value successfully, this function will also trigger related calculation and formatting events and update the appearance of the field.

Parameters
[in]valueNew value string. Specially, when current field is a list box field, this parameter can contain multiple values:
When to set multiple values, each value should be wrapped by "()". For example, "(ABC)(CCC)" means to set 2 value "ABC" and "CCC".
If a value contains "()", or "\" as its content, please add an additional "\" as an escape character just in front of each character of "()" or "\". For example:
  • "ABC" means to set the value "ABC".
  • "(ABC)" means to set the value "ABC".
  • "(ABC" means to set the value "(ABC".
  • "(\\(ABC\\)\\(BBB\\)\\(CCC\\))" means to set the value "(ABC)(BBB)(CCC)".
  • "456\\\\" means to set the value "456\".
  • "(\\(ABC\\))" means to set the value "(ABC)".
Returns
None.