Previous Next
Event Object
All JavaScripts are executed as the result of a particular event (also referred to as a trigger).
Acrobat Forms accepts the following events and executes any scripts that are specified for
these events: mouse enter, mouse down, mouse up, mouse exit, keystroke, format, validate, and
calculate. It is important to JavaScript writers to know what these events are and when and
what order they are processed.
Event Processing
Mouse Enter
The mouse enter event is triggered when a user moves the mouse pointer inside the rectangle
of a field. This is the typical place to open a text field to display help text, etc.
Mouse Down
The mouse down event is triggered when a user starts to click on a form field and the mouse
button is still down. It is advised that you perform very little processing (i.e. play a short
sound) during this event. A mouse down event will not occur unless a mouse enter event has
already occurred.
Mouse Up
The mouse up event is triggered when the user clicks on a form field and releases the mouse
button. This is the typical place to attach routines such as the submit action if a form. A mouse
up event will not occur unless a mouse down event has already occurred.
Mouse Exit
The mouse exit event is the opposite of the mouse enter event and occurs when a user moves
the mouse pointer outside of the rectangle of a field. A mouse exit event will not occur unless a
mouse enter event has already occurred.
Keystroke
The keystroke event occurs whenever a user types a keystroke into a text box or combo box
(this includes cut and paste operations), or selects an item in a combo box drop down or listbox
field. A keystroke script may want to limit the type of keys allowed. For example, a numeric
field might only allow numeric characters.
Acrobat Forms - JavaScript Object Specification 31
The user interface for Acrobat Forms allows the author to specify a Selection Change script for
list boxes. The script is triggered every time an item is selected. This is implemented as the
keystroke event where the keystroke value is equivalent to the user selection . This behavior is
also implemented for the combo box —the “keystroke” could be thought to be a paste into the
text field of the value selected from the drop down list.
There is a final call to the keystroke script before the validate event is triggered. This call sets
the willCommit property to true for the event. With keystroke processing, it is sometimes
useful to make a final check on the field value before it is committed (pre-commit). This
allows the script writer to gracefully handle particularly complex formats that can only be
partially checked on a keystroke by keystroke basis.
Validate
Regardless of the field type, user interaction with the field may produce a new value for that
field. After the user has either clicked outside a field, tabbed to another field, or pressed the
enter key, the user is said to have committed the new data value.
The validate event is the first event generated for a field after the value has been committed so
that a JavaScript can verify that the value entered was correct. If the validate event is
successful, the next event triggered is the calculate event.
Calculate
The calculate event causes all fields that have a calculation script attached to them to be
executed. All fields that depend on the value of the validated field will now be re-calculated.
These fields may in turn generate additional validate, calculate, and format events.
Calculated fields may have dependencies on other calculated fields whose values must be
determined beforehand. The calculation order array contains an ordered list of all the fields in
a document that have a calculation script attached. When a full calculation is needed, each of
the fields in the array is calculated in turn starting with the zeroth index of the array and
continuing in sequence to the end of the array.
To change the calculation order of fields, use the Tools->Forms->JavaScript->Set Calculation
Order... menu item in Adobe Acrobat.
Format
Once all dependent calculations have been performed the format event is triggered. This event
allows the attached JavaScript to change the way that the data value appears to a user (also
known as its presentation or appearance). For example, if a data value is a number and the
context in which it should be displayed is currency, the formatting script can add a dollar sign
($) to the front of the value and limit it to two decimal places past the decimal point.
Acrobat Forms - JavaScript Object Specification 32
Event Object Properties
change
Type: String Event: Keystroke, Selection ChangeAccess: R/W
This property specifies the change in value that the user has just typed. The change is
replaceable such that if the JavaScript wishes to substitute certain characters, it may.
commitKey 4.0
Type: Number Event: Keystroke, Format Access: R
Use this property to determine how a form field lost focus. Valid values are:
0 - value was not committed (e.g. escape key was pressed).
1 - value was committed because of a click outside the field using the mouse.
2 - value was committed because of hitting the enter key.
3 - value was committed by tabbing to a new field.
For example, to automatically display an alert dialog after a field has been committed add the
following to the field’s format script:
if (event.commitKey != 0)
app.alert(“Thank you for your new field value.”);
modifier
Type: Boolean Event: Keystroke, Mouse events Access: R
This property is a boolean that specifies whether the modifier key is down during a particular
event. The modifier key on the Microsoft Windows platform is Control and on the Macintosh
platform is Option or Command. The modifier property is not supported on UNIX.
rc
Type: Boolean Event: Keystroke, Validate Access: R/W
This property is used for validation. It indicates whether a particular event in the event chain
should succeed. Set rc to false to prevent a change from occurring or a value from committing.
By default rc is true.
Acrobat Forms - JavaScript Object Specification 33
For each event, except the mouse related events, the static event object is populated with the
following data. In most events, it is important for JavaScript to set the rc (return code)
property to indicate that the event can proceed.
selEnd
Type: Integer Event: Keystroke Access: R/W
This property specifies the ending position of the current text selection during a keystroke
event.
selStart
Type: Integer Event: Keystroke Access: R/W
This property specifies the starting position of the current text selection during a keystroke
event.
shift
Type: Boolean Event: Keystroke, Mouse events Access: R
This property is a boolean that specifies whether the shift key is down during a particular
event.
target
Type: Object Event: All events Access: R
This property contains the target object that triggered the event. In all mouse events it is the
field object that triggered the event. In other events like page open and close it is the document
or this Object.
value
Type: Various Event: Validate, Calculate, Format, SelChange Access: R/W
For the validate event, value is the value that the field contains when it is committed. The
current field value is the value property for the field. For example, the following JavaScript
verifies that the field value is between zero and 100.
Example:
if (event.value < 0 || event.value > 100) {
app.beep(0);
Acrobat Forms - JavaScript Object Specification 34
app.alert("Invalid value for field " + event.target.name);
event.rc = false;
}
For a calculate event, JavaScript should set this property. This is the value that the field should
take upon completion of the event. For example, the following JavaScript sets the calculated
value of the field to the value of the SubTotal field plus tax.
var f = this.getField("SubTotal");
event.value = f.value * 1.0725;
For a format event, JavaScript should set this property. This is the value used when generating
the appearance for the field. By default, it contains the value that the user has committed. For
example, the following JavaScript formats the field as a currency type of field.
event.value = util.printf("$%.2f", event.value);
willCommit
Type: Boolean Event: Keystroke Access: R
Use this property to verify the current keystroke event before the data is committed. This is
useful to check the target form field values and for example verify if character data instead of
numeric data was entered. JavaScript sets this property to true after the last keystroke event
and before the field is validated.
Example:
var value = event.value
if (event.willCommit)
// Final value checking.
else
// Keystroke level checking.
For more examples of using willCommit, refer to the Acrobat Forms JavaScript application
(Aform.js) in your Acrobat plug-ins directory.
Acrobat Forms - JavaScript Object Specification 35
Field Object
The Field object represents an Acrobat form field (that is, a field created using the Acrobat
form tool). In the same manner that an author might want to modify an existing field’s
properties like the border color or font, the Field object gives the JavaScript user the ability to
perform the same modifications.
Field Access from JavaScript
Before a field can be accessed, it must be “bound” to a JavaScript variable through a method
provided by the this Object methods interface. More than one variable may be bound to a field
by modifying the field’s object properties or accessing its methods. This affects all variables
bound to that field.
var f = doc.getField("Total");
This example allows the script to now manipulate the form field Total via the variable “f”.
Field Properties
The following is a chart of field property names used by Acrobat with Javascript and the field
properties that are available:
Field Property Type Text Combo List Push Check Radio Signa Read Write
Name Field Box Box Button Box Button ture Access Access
alignment String
borderStyle String
calcOrderIndex Integer
charLimit Integer
defaultValue String
delay boolean
display Integer
doc Object
editable Boolean
fillColor Array
hidden Boolean
Acrobat Forms - JavaScript Object Specification 36
Field Property Type Text Combo List Push Check Radio Signa Read Write
Name Field Box Box Button Box Button ture Access Access
highlight String
lineWidth Integer
lineWidth Boolean
name String
numItems Integer
password Boolean
print Boolean
readonly Boolean
required Boolean
strokeColor Array
style String
textColor Array
textColor String
textSize Integer
type String
userName String
value Various
alignment
Type: String Fields: Text Access: R/W
This property determines how the text is laid out within the text field. Valid alignments include
left, center, and right.
var f = this.getField("MyText");
f.alignment = "center";
Acrobat Forms - JavaScript Object Specification 37
borderStyle
Type: String Fields: All Access: R/W
This property specifies the border style for a field. Valid border styles include solid, dashed,
beveled, inset, and underline. The border style determines how the border for the rectangle is
drawn.
• The solid style strokes the entire perimeter of the rectangle with a solid line.
• The dashed style strokes the perimeter with a dashed line.
• The beveled style is equivalent to the solid style with an additional beveled
(pushed-out appearance) border applied inside the solid border.
• The inset style is equivalent to the solid style with an additional inset (pushed-in
appearance) border applied inside the solid border.
• The underline style strokes the bottom portion of the rectangle’s perimeter.
The border object is a static convenience constant that defines all the border styles of a field.
The following example illustrates how to set the border style of a field to solid:
var f = this.getField("MyField");
f.borderStyle = border.s; /* border.s evaluates to "solid" */
The following chart defines the borderStyle property and its associated keywords:
Type Keyword
solid border.s
beveled border.b
dashed border.d
inset border.i
underline border.u
calcOrderIndex
Type: Integer Fields: Text, Combo Box Access: R/W
Use this property to change the calculation order of fields in the document. When a computable
Text or Combo Box field is added to a document, it is added to the end of the document and the
field’s name is placed in the calculation order array. The calculation order array determines
the order fields are calculated in the document (see Event Processing for more information
about calculation order arrays). The calcOrderIndex property works similarly to the Calculate
tab used by the Acrobat Exchange Form tool. Note the following example:
Acrobat Forms - JavaScript Object Specification 38
var a = this.getField("newItem");
var b = this.getField("oldItem");
a.calcOrderIndex = b.calcOrderIndex + 1;
In this example, the this Object method getField, gets the newItem field that was added after
‘oldItem’ field. It then changes the calcOrderIndex of the oldItem field so that it is calculated
before ‘newItem’ field.
charLimit
Type: Integer Fields: Text Access: R/W
This property limits the number of characters that a user can type into a text field.
defaultValue
Type: String Fields: All but Button Access: R/W
This property exposes the default value of a field. This is the value that the field is set to when
the form is reset.
delay
Type: Boolean Fields: All Access: R/W
This property delays the redrawing of a field’s appearance. It is generally used to buffer a
series of changes to the properties of the field before requesting that the field regenerate its
appearance. Setting the property to true forces the field to wait until delay is set to false. The
update of its appearance then takes place, redrawing the field with its latest settings.
// Get the MyCheckBox field
var f = this.getField("MyCheckBox");
// set the delay and change the fields properties
// to beveled edge and medium thickness line.
f.delay = true;
f.borderStyle = border.b;
f.strokeWidth = 2;
// force the changes now
f.delay = false;
There is a corresponding document level delay flag if changes are being made to many fields at
once.
Acrobat Forms - JavaScript Object Specification 39
display 4.0
Type: Integer Fields: All Access: R/W
This property controls whether the field is hidden or visible on screen and in print:
Effect Keyword
Field is visible on screen and in print display.visible
Field is hidden on screen and in print display.hidden
Field is visible on screen but doesn’t print display.noPrint
Field is hidden on screen but prints display.noView
This property supersedes the older hidden and print properties.
doc
Type: Object Fields: All Access: R
This property defines the document the field belongs to. Its value is the this Object or the this
Object . Please refer to the this Object section for more details.
editable
Type: Boolean Fields: Combobox Access: R/W
Combo boxes can be editable, that is, the user can type in a selection. This property determines
whether the user can type in a selection or must choose one of the provided selections.
var f = this.getField("MyComboBox");
f.editable = true;
fillColor
Type: Array Fields: All Access: R/W
This property specifies the background color for a field. The background color is used to fill
the field’s rectangle. Values are defined by using transparent, gray, RGB or CMYK color.
Refer to the Global Object section for information on defining color arrays and how values are
used with this property.
var f = this.getField("MyField");
if (color.equal(f.fillColor, color.red))
Acrobat Forms - JavaScript Object Specification 40
Previous Next