Foxit PDF SDK
fsdk.Field Class Reference

Public Member Functions

def GetAlignment ()
 Get the alignment value.
More...
 
def GetAlternateName ()
 Get alternate name.
More...
 
def GetControl (page, index)
 Get a form control by index, in a specified PDF page.
More...
 
def GetControlCount (a, interface)
 Get count of form controls.
More...
 
def GetControlCount (page)
 Get count of form controls in a specified PDF page.
More...
 
def GetDefaultAppearance ()
 Get the default appearance data.
More...
 
def GetDefaultValue ()
 Get default value.
More...
 
def GetDefaultValueObj ()
 Get the PDF object of field's default value.
More...
 
def GetDict ()
 Get the PDF dictionary of current object.
More...
 
def GetFlags ()
 Get field flags.
More...
 
def GetInheritedAttribute (attribute_name)
 Get the PDF object for specified attribute which may be inherited from the ancestor node in the field tree.
More...
 
def GetMappingName ()
 Get mapping name.
More...
 
def GetMaxLength ()
 Get maximum length of the field's text, in characters.
More...
 
def GetName ()
 Get field name.
More...
 
def GetOptions ()
 Get options of list box or combo box.
More...
 
def GetTopVisibleIndex ()
 Get top index of option for scrollable list boxes.
More...
 
def GetType ()
 Get field type.
More...
 
def GetValue ()
 Get value.
More...
 
def GetValueObj ()
 Get the PDF object of field's value.
More...
 
def IsEmpty ()
 Check whether current object is empty or not.
More...
 
def Reset ()
 Reset data in current field to its default value. (Not support signature field)
More...
 
def SetAlignment (alignment)
 Set alignment property of a form, as a document-wide default value. (Not support signature field)
More...
 
def SetAlternateName (alternate_name)
 Set alternate name. (Not support signature field)
More...
 
def SetDefaultAppearance (default_ap)
 Set default appearance data.
More...
 
def SetDefaultValue (value)
 Set default value.
More...
 
def SetFlags (flags)
 Set field flags.
More...
 
def SetMappingName (name)
 Set mapping name. (Not support signature field)
More...
 
def SetMaxLength (max_length)
 Set maximum length of the field's text, in characters.
More...
 
def SetOptions (option_array)
 Set options of list box or combo box.
More...
 
def SetTopVisibleIndex (index)
 Set top index for scrollable list boxes.
More...
 
def SetValue (value)
 Set value.
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 fsdk.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 fsdk.FieldE_TypeSignature , the form field object is a signature object in fact.
To access additional actions, please construct an fsdk.AdditionalAction object with Field object.

See also
Form
fsdk.Signature
fsdk.AdditionalAction

Member Function Documentation

◆ GetAlignment()

def fsdk.Field.GetAlignment ( )

Get the alignment value.

Alignment is a property for variable text and it is only useful for text field, list box and combo 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 fsdk.E_AlignmentLeft and this would be one of these values.

◆ GetAlternateName()

def fsdk.Field.GetAlternateName ( )

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()

def fsdk.Field.GetControl (   page,
  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 fsdk.Field.GetControlCount with same parameter page.
Returns
form control object.

◆ GetControlCount() [1/2]

def fsdk.Field.GetControlCount (   a,
  interface 
)

Get count of form controls.

Returns
The count of the form controls.

◆ GetControlCount() [2/2]

def fsdk.Field.GetControlCount (   page)

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()

def fsdk.Field.GetDefaultAppearance ( )

Get the default appearance data.

Returns
The default appearance data.

◆ GetDefaultValue()

def fsdk.Field.GetDefaultValue ( )

Get default value.

Applicable for all fields except push button.

Returns
Default value string. For field types that are not applicable, an empty string will be returned.

◆ GetDefaultValueObj()

def fsdk.Field.GetDefaultValueObj ( )

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. If there is no "DV" entry or any error occurs, this function will return null.

◆ GetDict()

def fsdk.Field.GetDict ( )

Get the PDF dictionary of current object.

Returns
The PDF dictionary of current object. If there is any error, the function will return null.

◆ GetFlags()

def fsdk.Field.GetFlags ( )

Get field flags.

Field flags specifies various characteristics of a form field.

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

◆ GetInheritedAttribute()

def fsdk.Field.GetInheritedAttribute (   attribute_name)

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. If there is no entry which is specified by attribute_name or any error occurs, this function will return null.

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

◆ GetMappingName()

def fsdk.Field.GetMappingName ( )

Get mapping name.

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

Returns
The mapping name.

◆ GetMaxLength()

def fsdk.Field.GetMaxLength ( )

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()

def fsdk.Field.GetName ( )

Get field name.

Returns
Field name string.

◆ GetOptions()

def fsdk.Field.GetOptions ( )

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()

def fsdk.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 index of the first option visible in the list.

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

◆ GetType()

def fsdk.Field.GetType ( )

Get field type.

Returns
Form field type. Please refer to values starting from fsdk.FieldE_TypeUnknown and this would be one of these values.

◆ GetValue()

def fsdk.Field.GetValue ( )

Get value.

Applicable for all fields except push button. For field types that are not applicable, an empty string will be returned. For check box and radio box, this function will return the appearance state value.

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

◆ GetValueObj()

def fsdk.Field.GetValueObj ( )

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. If there is no "V" entry or any error occurs, this function will return null.

◆ IsEmpty()

def fsdk.Field.IsEmpty ( )

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.

◆ Reset()

def fsdk.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()

def fsdk.Field.SetAlignment (   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, list box and combo 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 fsdk.E_AlignmentLeft and this should be one of these values.
If other values is used to set, fsdk.E_AlignmentLeft will be used by default.
Returns
None.

◆ SetAlternateName()

def fsdk.Field.SetAlternateName (   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()

def fsdk.Field.SetDefaultAppearance (   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.
If text_size of input default appearance data is 0, that means the text size should be calculated automatically.
Returns
None.

◆ SetDefaultValue()

def fsdk.Field.SetDefaultValue (   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()

def fsdk.Field.SetFlags (   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 fsdk.FieldE_FlagReadOnly and this should be one or a combination of these values.
Returns
None.

◆ SetMappingName()

def fsdk.Field.SetMappingName (   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()

def fsdk.Field.SetMaxLength (   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()

def fsdk.Field.SetOptions (   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()

def fsdk.Field.SetTopVisibleIndex (   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 index of the first option visible in the list.

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

◆ SetValue()

def fsdk.Field.SetValue (   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.