Class PDFNet.Field
PDFNet.Field
| Constructor Attributes | Constructor Name and Description |
|---|---|
|
PDFNet.Field(leaf_node, builder)
An interactive form (sometimes referred to as an AcroForm) is a
collection of fields for gathering information interactively from
the user.
|
| Method Attributes | Method Name and Description |
|---|---|
|
assign(right)
Copy Constructor
|
|
| <static> |
PDFNet.Field.create(field_dict)
construct a PDF::Field from a SDF dictionary representing a terminal field node.
|
|
removes any appearances associated with the field.
|
|
|
findInheritedAttribute(attrib)
Some of the Field attributes are designated as inheritable.
|
|
|
flatten(page)
Flatten/Merge existing form field appearances with the page content and
remove widget annotation.
|
|
|
getFlag(flag)
|
|
|
getName()
|
|
|
getOpt(index)
|
|
|
Returns the total number of options in a list or combo box.
|
|
|
getTriggerAction(trigger)
[Documentation Not Yet Added]
|
|
|
getType()
|
|
|
getValue()
|
|
|
isAnnot()
|
|
|
isValid()
|
|
|
regenerates the appearance stream for the Widget Annotation containing
variable text.
|
|
|
rename(field_name)
modifies the field name.
|
|
|
setFlag(flag, value)
Flags specifying various characteristics of the fields.
|
|
|
sets the justification to be used in displaying the text field.
|
|
|
setMaxLen(max_len)
sets the maximum length of the field's text, in characters.
|
|
|
setValue(value)
Sets the value of the field (i.e.
|
|
|
setValueAsBool(value)
sets the value of a check-box or radio-button field.
|
|
|
setValueAsString(value)
sets the value of the field (i.e.
|
|
|
useSignatureHandler(signature_handler_id)
Sets the signature handler to use for adding a signature to this field.
|
Class Detail
PDFNet.Field(leaf_node, builder)
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:
- Parameters:
- leaf_node
- builder
Method Detail
assign(right)
Copy Constructor
- Parameters:
- {field} right
- (generated documentation)
<static>
{field}
PDFNet.Field.create(field_dict)
construct a PDF::Field from a SDF dictionary representing a terminal field node.
- Parameters:
- {Obj} field_dict
- the SDF dictionary to construct the field from.
- Returns:
- {field} A promise that resolves to an object of type: "field" (generated documentation)
eraseAppearance()
removes any appearances associated with the field.
{Obj}
findInheritedAttribute(attrib)
Some of the Field attributes are designated as inheritable.
If such an attribute is omitted from a Field object, its value is inherited
from an ancestor node in the Field tree. If the attribute is a required one,
a value must be supplied in an ancestor node; if it is optional and no
inherited value is specified, the default value should be used.
The function walks up the Field inheritance tree in search for specified
attribute.
- Parameters:
- {string} attrib
- (generated documentation)
- Returns:
- {Obj} A promise that resolves to the attribute value if the given attribute name was found or a NULL object if the given attribute name was not found. Resources dictionary (Required; inheritable) MediaBox rectangle (Required; inheritable) CropBox rectangle (Optional; inheritable) Rotate integer (Optional; inheritable)
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:
- {Page} page
- page object to flatten
{GState}
getDefaultAppearance()
- Returns:
- {GState} 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.
{Obj}
getDefaultValue()
- Returns:
- {Obj} 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.
{string}
getDefaultValueAsString()
- Returns:
- {string} 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.
{boolean}
getFlag(flag)
- Parameters:
- {number/enum} flag
- (generated enum documentation)
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:
- {boolean} A promise that resolves to the value of given field flag
{number}
getJustification()
Return value enum:
PDFNet.Field.TextJustification = {
e_left_justified : 0
e_centered : 1
e_right_justified : 2
}
- Returns:
- {number} A promise that resolves to the form of quadding (justification) to be used in displaying the text fields.
{number}
getMaxLen()
- Returns:
- {number} 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.
{string}
getName()
- Returns:
- {string} A promise that resolves to a string representing the fully qualified name of the field (e.g. "employee.name.first").
{string}
getOpt(index)
- Parameters:
- {number} index
- index position of the option to retrieve.
- Returns:
- {string} A promise that resolves to the string of the option at the givent index.
{number}
getOptCount()
Returns the total number of options in a list or combo box.
- Returns:
- {number} A promise that resolves to an object of type: "number" (generated documentation)
{string}
getPartialName()
- Returns:
- {string} 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).
{Obj}
getSDFObj()
- Returns:
- {Obj} A promise that resolves to the underlying SDF/Cos object.
{Obj}
getTriggerAction(trigger)
[Documentation Not Yet Added]
- Parameters:
- {number/enum} trigger
- (generated enum documentation)
PDFNet.Field.EventType = { e_action_trigger_keystroke : 13 e_action_trigger_format : 14 e_action_trigger_validate : 15 e_action_trigger_calculate : 16 }
- Returns:
- {Obj} A promise that resolves to an object of type: "Obj" (generated documentation)
{number}
getType()
Return value enum:
PDFNet.Field.Type = {
e_button : 0
e_check : 1
e_radio : 2
e_text : 3
e_choice : 4
e_signature : 5
e_null : 6
}
- Returns:
- {number} 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.
{rect}
getUpdateRect()
- Returns:
- {rect} A promise that resolves to the rectangle that should be refreshed after changing a field.
{Obj}
getValue()
- Returns:
- {Obj} 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.
{boolean}
getValueAsBool()
- Returns:
- {boolean} A promise that resolves to field value as a boolean.
{string}
getValueAsString()
- Returns:
- {string} 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.
{boolean}
isAnnot()
- Returns:
- {boolean} A promise that resolves to true if this Field is a Widget Annotation Determines whether or not this Field is an Annotation.
{boolean}
isValid()
- Returns:
- {boolean} 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.
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:
- {string} field_name
- a string representing the fully qualified name of the field (e.g. "employee.name.first").
setFlag(flag, value)
Flags specifying various characteristics of the fields.
Field flags common to all field types:
----------------------------------------------
If e_read_only flag is 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.
If e_required flag is set, the field must have a value at the time
it is exported by a submit-form action.
If e_no_export flag is set, the field must not be exported by a
submit-form action.
Field flags specific to radio buttons:
----------------------------------------------
If e_toggle_to_off is clear, exactly one radio button must be selected
at all times; clicking the currently selected button has no effect.
If set, clicking the selected button deselects it, leaving no button selected.
If e_radios_in_unison is 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 (the same behavior as HTML radio buttons).
Field flags specific to text fields:
----------------------------------------------
If e_multiline is set, the field can contain multiple lines of text;
if clear, the field's text is restricted to a single line.
If e_password 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. The value is not stored if this flag is set.
If e_file_select is set, the text entered in the field represents the pathname
of a file whose contents are to be submitted as the value of the field.
If e_no_spellcheck is set, text entered in the field is not spell-checked.
If e_no_scroll is 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.
If e_comb is set, the field is automatically divided into as many equally
spaced positions, or combs, as the value of MaxLen, and the text is laid out
into those combs. Meaningful only if the MaxLen entry is present in the text
field and if the Multiline, Password, and FileSelect flags are clear.
If e_rich_text is set, the value of this field should be represented as a rich
text string. If the field has a value, the RV entry of the field dictionary
specifies the rich text string.
Field flags specific to choice fields:
----------------------------------------------
If e_combo is set, the field is a combo box;
if clear, the field is a list box.
If e_edit is set, the combo box includes an editable text box as well as a
dropdown list; if clear, it includes only a drop-down list. This flag is
meaningful only if the e_combo flag is set.
If e_sort is set, the field's option items should be sorted alphabetically.
This flag is intended for use by form authoring tools, not by PDF viewer
applications. Viewers should simply display the options in the order in
which they occur in the Opt array.
If e_multiselect is set, more than one of the field's option items may be
selected simultaneously; if clear, no more than one item at a time may be
selected.
If e_commit_on_sel_change is set, the new value is committed as soon as a
selection is made with the pointing device. This option enables applications
to perform an action once a selection is made, without requiring the user
to exit the field. If clear, the new value is not committed until the user
exits the field.
- Parameters:
- {number/enum} flag
- (generated enum documentation)
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 } - {boolean} value
- (generated documentation)
setJustification(j)
sets the justification to be used in displaying the text field.
- Parameters:
- {number} j
- 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:
- {number} max_len
- maximum length of a field's text.
{ViewChangeCollection}
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:
- {Obj} value
- the new field value.
- Returns:
- {ViewChangeCollection} A promise that resolves to an object of type: "ViewChangeCollection" (generated documentation)
{ViewChangeCollection}
setValueAsBool(value)
sets the value of a check-box or radio-button field.
- Parameters:
- {boolean} value
- If true, the filed will be set to 'True', if false the field will be set to 'False'.
- Returns:
- {ViewChangeCollection} A promise that resolves to an object of type: "ViewChangeCollection" (generated documentation)
{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:
- {string} value
- the new field value.
- Returns:
- {ViewChangeCollection} A promise that resolves to an object of type: "ViewChangeCollection" (generated documentation)
{Obj}
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:
- {number} signature_handler_id
- The unique id of the SignatureHandler to use for adding signature in this field.
- Returns:
- {Obj} A promise that resolves to the signature dictionary created using the SignatureHandler, or NULL pointer if the signature handler is not found.