Class: Field

PDFNet. Field


new Field()

An interactive form (sometimes referred to as an AcroForm) is a collection of fields for gathering information interactively from the user. A PDF document may contain any number of Fields appearing on any combination of pages, all of which make up a single, global interactive form spanning the entire document.

PDFNet fully supports reading, writing, and editing PDF forms and provides many utility methods so that work with forms is simple and efficient. Using PDFNet forms API arbitrary subsets of form fields can be imported or exported from the document, new forms can be created from scratch, and the appearance of existing forms can be modified.

In PDFNet Fields are accessed through FieldIterator-s. The list of all Fields present in the document can be traversed as follows:

FieldIterator itr = pdfdoc.GetFieldIterator();
for(; itr.HasNext(); itr.Next()) {
  Field field = itr.Current();
  Console.WriteLine("Field name: {0}", field.GetName());
 }

For a full sample, please refer to 'InteractiveForms' sample project.

To search field by name use FieldFind method. For example:

FieldIterator itr = pdfdoc.FieldFind("name");
if (itr.HasNext()) {
  Console.WriteLine("Field name: {0}", itr.Current().GetName());
}
else { ...field was not found... }

If a given field name was not found or if the end of the field list was reached the iterator HasNext() will return false.

If you have a valid iterator you can access the Field using Current() method. For example: Field field = itr.Current();

Using Flatten(...) method it is possible to merge field appearances with the page content. Form 'flattening' refers to the operation that changes active form fields into a static area that is
part of the PDF document, just like the other text and images in the document. A completely flattened PDF form does not have any widget annotations or interactive fields.

Methods


<static> create(field_dict)

construct a PDF::Field from a SDF dictionary representing a terminal field node.

Parameters:
Name Type Description
field_dict PDFNet.Obj

the SDF dictionary to construct the field from.

Returns:

A promise that resolves to an object of type: "field"

Type
PDFNet.Field

assign(right)

Copy Constructor

Parameters:
Name Type Description
right PDFNet.Field

eraseAppearance()

removes any appearances associated with the field.


findInheritedAttribute(attrib)

Parameters:
Name Type Description
attrib string
Returns:

A promise that resolves to an object of type: "Obj"

Type
PDFNet.Obj

flatten(page)

Flatten/Merge existing form field appearances with the page content and remove widget annotation.

Form 'flattening' refers to the operation that changes active form fields into a static area that is part of the PDF document, just like the other text and images in the document. A completely flattened PDF form does not have any widget annotations or interactive fields.

Parameters:
Name Type Description
page PDFNet.Page

page object to flatten


getDefaultAppearance()

Returns:

A promise that resolves to the default graphics state that should be used in formatting the text. The state corresponds to /DA entry in the field dictionary.

Type
PDFNet.GState

getDefaultValue()

Returns:

A promise that resolves to the default value to which the field reverts when a reset-form action is executed or NULL if the default value is not specified.

The format of field's value varies depending on the field type.

Type
PDFNet.Obj

getDefaultValueAsString()

Returns:

A promise that resolves to a string of the default value to which the field reverts when a reset-form action is executed or NULL if the default value is not specified.

The format of field's value varies depending on the field type.

Type
string

getFlag(flag)

Parameters:
Name Type Description
flag number/enum
PDFNet.Field.Flag = {
	e_read_only : 0
	e_required : 1
	e_no_export : 2
	e_pushbutton_flag : 3
	e_radio_flag : 4
	e_toggle_to_off : 5
	e_radios_in_unison : 6
	e_multiline : 7
	e_password : 8
	e_file_select : 9
	e_no_spellcheck : 10
	e_no_scroll : 11
	e_comb : 12
	e_rich_text : 13
	e_combo : 14
	e_edit : 15
	e_sort : 16
	e_multiselect : 17
	e_commit_on_sel_change : 18
}
Returns:

A promise that resolves to the value of given field flag

Type
boolean

getJustification()

Returns:

A promise that resolves to the form of quadding (justification) to be used in displaying the text fields.

Type
number
Example
Return value enum:
<pre>
PDFNet.Field.TextJustification = {
	e_left_justified : 0
	e_centered : 1
	e_right_justified : 2
}
</pre>

getMaxLen()

Returns:

A promise that resolves to the maximum length of the field's text, in characters, or a negative number if the length is not limited.

Type
number

getName()

Returns:

A promise that resolves to a string representing the fully qualified name of the field (e.g. "employee.name.first").

Type
string

getOpt(index)

Parameters:
Name Type Description
index number

index position of the option to retrieve.

Returns:

A promise that resolves to the string of the option at the givent index.

Type
string

getOptCount()

Returns the total number of options in a list or combo box.

Returns:

A promise that resolves to an object of type: "number"

Type
number

getPartialName()

Returns:

A promise that resolves to a string representing the partial name of the field (e.g. "first" when "employee.name.first" is fully qualified name).

Type
string

getSDFObj()

Returns:

A promise that resolves to the underlying SDF/Cos object.

Type
PDFNet.Obj

getTriggerAction(trigger)

Get the Action associated with the selected Field Trigger event.

Parameters:
Name Type Description
trigger number/enum
PDFNet.Field.EventType = {
	e_action_trigger_keystroke : 13
	e_action_trigger_format : 14
	e_action_trigger_validate : 15
	e_action_trigger_calculate : 16
}

the type of trigger event to get

Returns:

A promise that resolves to the Action Obj if present, otherwise NULL

Type
PDFNet.Obj

getType()

Returns:

A promise that resolves to the field's value, whose type/format varies depending on the field type. See the descriptions of individual field types for further information.

Type
number
Example
Return value enum:
<pre>
PDFNet.Field.Type = {
	e_button : 0
	e_check : 1
	e_radio : 2
	e_text : 3
	e_choice : 4
	e_signature : 5
	e_null : 6
}
</pre>

getUpdateRect()

Returns:

A promise that resolves to the rectangle that should be refreshed after changing a field.

Type
PDFNet.rect

getValue()

Returns:

A promise that resolves to the value of the Field (the value of its /V key) or NULL if the value is not specified.

The format of field's value varies depending on the field type.

Type
PDFNet.Obj

getValueAsBool()

Returns:

A promise that resolves to field value as a boolean.

Type
boolean

getValueAsString()

Returns:

A promise that resolves to a string of the value of the Field (the value of its /V key) or NULL if the value is not specified.

The format of field's value varies depending on the field type.

Type
string

isAnnot()

Returns:

A promise that resolves to true if this Field is a Widget Annotation

Determines whether or not this Field is an Annotation.

Type
boolean

isValid()

Returns:

A promise that resolves to whether this is a valid (non-null) Field. If the function returns false the underlying SDF/Cos object is null and the Field object should be treated as null as well.

Type
boolean

refreshAppearance()

regenerates the appearance stream for the Widget Annotation containing variable text. Call this method if you modified field's value and would like to update field's appearance.


rename(field_name)

modifies the field name.

Parameters:
Name Type Description
field_name string

a string representing the fully qualified name of the field (e.g. "employee.name.first").


setFlag(flag, value)

Parameters:
Name Type Description
flag number/enum
PDFNet.Field.Flag = {
	e_read_only : 0
	e_required : 1
	e_no_export : 2
	e_pushbutton_flag : 3
	e_radio_flag : 4
	e_toggle_to_off : 5
	e_radios_in_unison : 6
	e_multiline : 7
	e_password : 8
	e_file_select : 9
	e_no_spellcheck : 10
	e_no_scroll : 11
	e_comb : 12
	e_rich_text : 13
	e_combo : 14
	e_edit : 15
	e_sort : 16
	e_multiselect : 17
	e_commit_on_sel_change : 18
}
value boolean

setJustification(j)

sets the justification to be used in displaying the text field.

Parameters:
Name Type Description
j number/enum
PDFNet.Field.TextJustification = {
	e_left_justified : 0
	e_centered : 1
	e_right_justified : 2
}

enum representing justification to set the text field to, options are e_left_justified, e_centered and e_right_justified


setMaxLen(max_len)

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

Parameters:
Name Type Description
max_len number

maximum length of a field's text.


setValue(value)

Sets the value of the field (i.e. the value of the field's /V key). The format of field's value varies depending on the field type.

Parameters:
Name Type Description
value PDFNet.Obj

the new field value.

Returns:

A promise that resolves to an object of type: "ViewChangeCollection"

Type
PDFNet.ViewChangeCollection

setValueAsBool(value)

sets the value of a check-box or radio-button field.

Parameters:
Name Type Description
value boolean

If true, the filed will be set to 'True', if false the field will be set to 'False'.

Returns:

A promise that resolves to an object of type: "ViewChangeCollection"

Type
PDFNet.ViewChangeCollection

setValueAsString(value)

sets the value of the field (i.e. the value of the field's /V key). The format of field's value varies depending on the field type.

Parameters:
Name Type Description
value string

the new field value.

Returns:

A promise that resolves to an object of type: "ViewChangeCollection"

Type
PDFNet.ViewChangeCollection

useSignatureHandler(signature_handler_id)

Sets the signature handler to use for adding a signature to this field. If the signature handler is not found in PDFDoc's signature handlers list, this field will not be signed. To add signature handlers, use PDFDoc.AddSignatureHandler method.

If a signature handler is already assigned to this field and this method is called once again, the associate signature handler for this field will be updated with the new handler.

Parameters:
Name Type Description
signature_handler_id number

The unique id of the SignatureHandler to use for adding signature in this field.

Returns:

A promise that resolves to the signature dictionary created using the SignatureHandler, or NULL pointer if the signature handler is not found.

Type
PDFNet.Obj