Previous Next
f.fillColor = color.blue;
else
f.fillColor = color.yellow;
In older versions of this specification, this property was named bgColor. The use of bgColor is
now discouraged but for backwards compatibility is still valid.
hidden
Type: Boolean Fields: All Access: R/W
This property controls whether the field is hidden or visible to the user. If the value is false the
field is visible, true the field is invisible. The default value for hidden is false.
// Set the field to hidden
var f = this.getField("MyField");
f.hidden = true;
See also the display property which supersedes this property in later versions.
highlight
Type: String Fields: Button Access: R/W
This property defines how a button reacts when a user clicks it. The four highlight modes
supported are none, invert, push and outline.
• The none highlight does not indicate visually that the button has been clicked.
• The invert highlight causes the region encompassing the button’s rectangle to invert
momentarily.
• The push highlight displays the down face for the button (if any) momentarily.
• The outline highlight causes the border of the rectangle to invert momentarily.
The ‘highlight’ object defines all the characteristics that a button can have. Use it in your
scripts to access the highlight of choice. The following chart shows the highlight object and its
associated keywords:
Type Keyword
none highlight.n
invert highlight.i
push highlight.p
outline highlight.o
Acrobat Forms - JavaScript Object Specification 41
The following example sets the highlight property of a button to “invert”.
// set the highlight mode on button to invert
var f = this.getField("MyButton");
f.highlight = highlight.i;
lineWidth
Type: Integer Fields: All Access: R/W
This property specifies the thickness of the border when stroking the perimeter of a field’s
rectangle. If the stroke color is transparent, this parameter has no effect except in the case of a
beveled border. You can set the lineWidth property in JavaScript by using the integer values
below:
Line Width Key Value
none 0
thin 1
medium 2
thick 3
For example:
// Change the border width of the Text Box to medium thickness
f.lineWidth = 2
The default value for lineWidth is 1 (thin). Any integer value can be used. However, values
beyond 5 may distort the field’s appearance.
In older versions of this specification, this property was borderWidth. The use of borderWidth
is now discouraged but for backwards compatibility is still valid.
multiline
Type: Boolean Fields: Text Access: R
This read-only property determines how the text is wrapped within the field. Text fields can be
single line (clip to field boundaries) or multi-line (wrap to field boundaries).
name
Type: String Fields: All Access: R
Acrobat Forms - JavaScript Object Specification 42
This property allows you to access the fully qualified field name of the field as a string object.
var f = this.getField("MyField");
console.println(f.name);
numItems
Type: Integer Fields: Combo & Listbox Access: R
The number of items in the combo or list box.
password
Type: Boolean Fields: Text Access: R
This property causes the field to display asterisks for the data entered into the field. Upon
submission, the actual data entered is sent. Fields that have the password attribute set will not
have the data in the field saved when the document is saved to disk.
print L
Type: Boolean Fields: All Access: R/W
This property determines whether a given field prints or not. Set the print property to true to
allow the field to appear when the user prints the document, set it to false to prevent printing.
This property can be used to hide control buttons and other fields that are not useful on the
printed page.
var f = this.getField("MyField");
f.print = false;
This property has been superseded by the display property and its use is discouraged.
readonly
Type: Boolean Fields: All Access: R/W
This property sets or gets the read-only characteristic of a field. If a field is read-only, the user
can see the field but cannot change it.
required
Type: Boolean Fields: All but Button Access: R/W
Acrobat Forms - JavaScript Object Specification 43
This property sets or gets the required characteristic of a field. If a field is required its value
must be non-null when the user clicks a submit button that causes the value of the field to be
posted. If the field value is null, the user receives a warning message and the submit does not
occur.
var f = this.getField("MyField");
f.required = true;
strokeColor
Type: Array Fields: All Access: R/W
This property specifies the stroke color for a field which is used to stroke the field’s rectangle
with a line as large as the line width. Values are defined by using transparent, gray, RGB or
CMYK color. Refer to the Color Arrays section for information on defining color arrays and how
values are used with this property.
In older versions of this specification, this property was borderColor. The use of borderColor is
now discouraged but for backwards compatibility is still valid.
style
Type: String Fields: Checkbox, Radio Button Access: R/W
This property allows the user to set the style of a check box or a radio button, that is, sets the
glyph used to indicate that the check box or radio button has been selected. Valid styles
include check, cross, diamond, circle, star, and square. The following defines the style
properties and the associated keywords:
Style Keyword
check style.ch
cross style.cr
diamond style.di
circle style.ci
star style.st
square style.sq
The following example illustrates the use if this property and the style object:
var f = this.getField("MyCheckbox");
f.style = style.ci;
Acrobat Forms - JavaScript Object Specification 44
textColor
Type: Array Fields: All Access: R/W
This property determines the foreground color of a field. It represents the text color for text,
button, or list box fields and the check color for check box or radio button fields. Values are
defined the same as the fillColor property. Refer to the Color Arrays section for information on
defining color arrays and how values are set and used with this property.
var f = this.getField("MyField");
f.textColor = color.red;
In older versions of this specification, this property was fgColor. The use of fgColor is now
discouraged but for backwards compatibility is still valid.
textFont
Type: String Fields: Text, Combo, List & Button Access: R/W
The textFont property determines the font that is used when laying out text in a text field,
combo box, list box or button. Valid fonts are defined as properties of the “font” object as
follows:
Text Font Keyword
Times-Roman font.Times
Times-Bold font.TimesB
Times-Italic font.TimesI
Times-BoldItalic font.TimesBI
Helvetica font.Helv
Helvetica-Bold font.HelvB
Helvetica-Oblique font.HelvI
Helvetica-BoldOblique font.HelvBI
Courier font.Cour
Courier-Bold font.CourB
Courier-Oblique font.CourI
Courier-BoldOblique font.CourBI
Symbol font.Symbol
ZapfDingbats font.ZapfD
Acrobat Forms - JavaScript Object Specification 45
The following example illustrates the use of this property and the font object.
// set the font of MyField to Helvetica
var f = this.getField("MyField");
f.textFont = font.Helv;
textSize
Type: Integer Fields: All Access: R/W
This property determines the text size in points that is used in all controls. In combo box and
radio button fields, the text size determines the size of the check. Valid text sizes include zero
and the range from 4 to 144 inclusive. A text size of zero means that the largest point size that
can still fit in the field’s rectangle should be used (in multi-line text fields and buttons this is
always 12 point).
// set the text size of MyField to 28 point
var f = this.getField("MyField");
f.textSize = 28;
type
Type: String Fields: All Access: R
This read-only property returns the type of the field as a string. Valid types that are returned
include button, checkbox, combobox, listbox, radiobutton, and signature.
userName
Type: String Fields: All Access: R/W
This property returns/sets the user name of the field (short description) as a string. The user
name is intended to be used as tool tip text whenever the mouse cursor enters a field. It can
also be used as a user friendly name when generating error messages instead of the field name
(which can sometimes not be suitable for human consumption).
value
Type: Various Fields: All But Button Access: R/W
This property gets the value of the field data that the user has entered. Depending on the type
of the field, the value may be a string, date, or number. Typically, the value is used to create
calculated fields.
var oil = this.getField("Oil");
Acrobat Forms - JavaScript Object Specification 46
var filter = this.getField("Filter");
event.value = (oil.value + filter.value) * 1.0725;
In this example, the value of the field being calculated is set to the sum of the oil and filter
fields and multiplied by the state sales tax. Value is perhaps the most important of all the field
properties.
Field Methods
buttonImportIcon
Parameter: none
Returns: nothing
This method imports the appearance of a button from another PDF file. It prompts the user to
select a PDF file available on the system.
clearItems
Parameters: none
Returns: nothing
This method clears all the values in a list box or combo box.
// Clear the field MyListbox
var f = this.getField("MyListBox");
f.clearItems();
deleteItemAt 4.0
Parameters: [nIndex]
Returns: nothing
This function deletes an item in a combo box or a list box. The parameter nIndex is the index of
the item in the list to delete (zero-based). If nIndex is not specified then the currently selected
item is deleted.
var a = this.getField("MyListBox");
a.deleteItemAt();
getArray
Parameters: None
Returns: an array of fields.
Acrobat Forms - JavaScript Object Specification 47
This function returns an array of terminal children fields (i.e. fields that can have a value) for a
parent field. This method can be particularly useful for doing field calculations in tables where
a parent field value is the sum of all of its children. To understand more about field name and
hierarchies, please see the section on Field Properties.
// f has 3 children: f.v1, f.v2, f.v3
var f = this.getField("f");
var a = f.getArray();
var v = 0.0;
for (j =0; j < a.length; j++)
v += a[j].value;
// v contains the sum of all the children of field "f"
getItemAt
Parameters: nIndex
Returns: internal value in an item in a list or combo box
This function gets the internal value of an item in a combo box or a list box. The parameter
nIndex is the index of the item in the list to obtain. If nIndex is set to -1, it returns the value of
the last item in the list. The getItemAt function returns the exported or internal value of the
item at nIndex in the combo box or list box.
// returns value of first item in list l
var a = this.getField("MyListBox");
var v = a.getItemAt(0);
insertItemAt
Parameters: cName, cExportValue, [nIndex]
Returns: nothing
This function inserts a new item into a combo box or a list box. cName is the index at which to
insert the item in a list box or combo box. cExportValue is the string export value of the item
i.e. internal value of the item being inserted. nIndex is the index in the list to insert the item at.
If nIndex is 0, cName is inserted at the top of the list. If nIndex is –1, cName is inserted at the
end of the list. The default value for nIndex is 0.
var l = this.getField("l"); /* l is a list box */
var v =l.insertItemAt("sam", "s", 0); /* inserts sam to top of list l */
setItems 4.0
Parameters: array
Acrobat Forms - JavaScript Object Specification 48
Returns: nothing
This method sets the list of items for a combo box or a list box. The single parameter necessary
to call this method must be an array. Each element in the array must either be an object
convertible to a string or another array. If the element can be converted to a string, the user and
export values for the list item are equal to the string. If the element is an array it must consist
of two sub-elements. The first sub-element should be convertible to a string which will be used
as the user value, the second element will be used as the export value.
var l = this.getField("ListBox");
l.setItems(["One", "Two", "Three"]);
var c = this.getField("StateBox");
c.setItems([["California", "CA"],["Massachusetts", "MA"],["Arizona", "AZ"]]);
var c = this.getField("NumberBox");
c.setItems(["1", 2, 3, ["PI", Math.PI]]);
See also the clearItems, getItemAt, and insertItemAt field methods.
Acrobat Forms - JavaScript Object Specification 49
Global Object
The Global object is a static JavaScript object that allows you to share data between documents
and have data be persistent across sessions. This is referred to as persistent global data.
Global data-sharing and notification across documents is done through a publish and subscribe
mechanism. This mechanism gives you the ability to monitor global data variables and report
their value changes across documents.
Global data can be specified by adding properties to the global object. The property type can
be a string, a boolean, or a number. For example, to add a variable called “volume” and to
allow all document scripts to have access to this variable, a script would simply define it as:
global.volume = 80;
To delete a variable or a property from the global object, use the delete operator to remove the
defined property. For more information on the reserved JavaScript keyword delete, please see
Netscape’s JavaScript Reference Manual. For example, to remove the property “volume” from
the global object, call the following script:
delete global.volume
Global Object Methods
setPersistent
parameters: cVariable, bPersist
Returns: none
This method sets cVariable to be persistent. It requires that bPersist is set true. This means the
cVariable will exist across invocations of Acrobat Exchange or Reader. If bPersist is false (the
default for any global property) then the property will be accessible across documents but not
across the Acrobat Viewer sessions. For example, to make the “volume” property persistent
and accessible for other documents you could use:
global.setPersistent("volume", true);
Note: Persistent global data only applies to variables of type boolean, number or
string. For all persistent data there is a 32k limit for the maximum size of
the global persistent variables. Any data added to the string after the 32k
limit will be dropped.
It is recommended that JavaScript developers building scripts for Acrobat Forms, utilize some
type of naming convention when specifying persistent global variables. One suggestion is to
start all variables with your company name. For example, if your company name is Xyz, start
Acrobat Forms - JavaScript Object Specification 50
Previous Next