AcroTex Acrobat Javascript

AcroTEX.
Net
eforms and insdljs Documentation
Support for AcroForms and Links,

and for
Document JavaScript and Open Page

Events
D. P. Story
The AeB eforms MANUAL
Copyright © 2019 [email protected]

Distribution Dated: 2019/05/24 http://www.acrotex.net
Table of Contents
PDF Links and Forms 4

1 Package Requirement and Options 4
1.1 Package Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 Package Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 The preview option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4 The useui option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.5 The unicode option of hyperref . . . . . . . . . . . . . . . . . . . . . . . 7
2 Form Fields 7
2.1 Button Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 Choice Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.3 Text Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.4 Signature Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3 Link Annotations 18
4 Actions 19
4.1 Trigger Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.2 Action Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5 JavaScript 26
5.1 Support of JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.2 Defining JavaScript Strings with \defineJSStr . . . . . . . . . . . . . 29
6 The useui option: A User-Friendly Interface 30

6.1 The Appearance Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.2 The Action Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.3 The Signed Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Setting the Tab Order 41

7 Setting the Tab Order 41
7.1 Using \setTabOrderByList . . . . . . . . . . . . . . . . . . . . . . . . . 42
7.2 Using \setTabOrderByNumber . . . . . . . . . . . . . . . . . . . . . . . . 43
Document and Page JavaScript 45

8 Package Options 45
Table of Contents (cont.) 3
9 The insDLJS and insDLJS* Environments 45

9.1 What is Document Level JavaScript? . . . . . . . . . . . . . . . . . . . . . 46
9.2 The insDLJS Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 46
9.3 The insDLJS* Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 48
9.4 Escaping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
9.5 Access and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
9.6 JavaScript References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
10 Open Action 51
11 The execJS Environment 52
12 The defineJS Environment 53
Appendices 57
A The Annotation Flag F 57
B Annotation Field flags Ff 58
C Supported Key Variables 59
References 67
4
PDF Links and Forms

In this document we describe the support for Acrobat form elements in an AcroTEX
document. The PDF Reference indicates there are four different categories of fields for
a total of seven types of fields.
1. Button Fields
(a) Push Button

(b) Check Box
(c) Radio Button
2. Choice Fields
(a) List Box

(b) Combo Box
3. Text Fields
4. Signature Fields
The AcroTEX Bundle now supports signature fields. Using the command \sigField, an
unsigned signature field is created. The field can be signed, either by using Acrobat, or
programmatically from a LATEX source, but you need to use aeb_pro and to create the
PDF using Acrobat Distiller.
The hyperref Package (Rahtz, Oberdiek et al) provides support for the same set
of form fields; however, not all features of these fields can be accessed through the
hyperref commands. I was determined to write my own set of commands which would
be sufficiently comprehensive and extendable to suit all the needs of the AcroTEX Bundle.
All the quiz environments have been modified to use this new set of form commands,
in this way, there is a uniform treatment of all form fields in the AcroTEX Bundle.
The demo files for eForm support are eqform.tex, for those using the Acrobat
Distiller to create a PDF document, and eqform_pd.tex, for those who use pdftex or
dvipdfm.
Online Resources: The following online resources are recommended:
• Core JavaScript Reference at Mozilla Developer Center.
• JavaScript for Acrobat API Reference at the Acrobat Developer Center. In the nav-
igation panel on the left, select JavaScript.
• PDF Blog, by D. P. Story.
• AeB Blog, by D. P. Story.

1. Package Requirement and Options

Prior to Exerquiz version 5.9, eforms was an integral part of Exerquiz. I’ve now sepa-
rated the two, making eforms into a stand-alone package that is called by Exerquiz.
Package Requirement and Options 5
1.1. Package Requirements

The eforms package requires hyperref (a newer version) and insdljs, a package that is
part of the AcroTEX Bundle.
1.2. Package Options

The eforms package has the usual driver options:
dvipsone, dvips, pdftex, dvipdfm, dvipdfmx, xetex
The package also works correctly with the luatex executable. Informing the package
what driver you are using is important, because each driver has its own code that needs
to be used to create form fields. For dvips, you should use
\usepackage[dvips]{eforms}
The eforms package now does automatic detection of pdftex (including luatex) and
xetex. If the web or exerquiz package is used, eforms will use the driver defined in
these earlier included packages.
A minimal document is
\documentclass{article}
\usepackage{eforms} % <-- the driver is pdftex, lualatex, or xetex
\begin{document}
% Content containing form fields, such as…
Don’t \pushButton[\CA{Push Me}]{myButton}{}{12bp},
I fall down easily.
\end{document}
The eforms package brings in the hyperref package and passes it the driver, so there
is no need to specify hyperref, usually. If you wish to introduce hyperref yourself with
specific options, place it before eforms.
If you use the exerquiz package, exerquiz brings in the eforms package and passes
the driver to it.
1.3. The preview option

When the preview option is taken, a frame box is drawn around any form field created
by eforms, making the position of the field visible in the DVI previewer or PDF reader.
Being able to view the position of a form element is important to determine whether
any additional adjustments in position is. Turn off this option when you build the final
version of the document.
This option was originally developed for those using a DVI previewer, it is also useful
for those using PDF creators pdflatex, xelatex, or lualatex. Modern LATEX users employ
quicker PDF readers such as sumatraPDF or PDF-Exchange; these non-conforming PDF

readers may not create form field appearances as Adobe Reader and Acrobat do; con-
sequently, an outline of the positions of the fields is most welcome.
\ifpreview The preview option just sets a switch (\ifpreview), which can conveniently be
Package Requirement and Options 6
\previewOn turned off and on using the commands \previewOn and \previewOff within the doc-
\previewOff ument itself. Related to \previewOn and \previewOff is the command \pmpvOn (poor
man’s preview), covered in the next paragraph.
Enhanced preview (Poor man’s preview). The \pushButton command of eforms pro-
duces a pushbutton;1 a common key to use is the \CA key, the value of which captions
\pmpvOn the button. As a companion to \previewOn, eforms defines \pmpvOn and \pmpvOff;
\pmpvOff when \previewOn is in effect, expanding \pmpvOn causes the value of the \CA key to
be typeset into the pushbutton preview; for example,
\previewOn\pmpvOn % <--enhanced preview activated

...
\pushButton[\CA{Push Me}]{pbDemo}{}{13bp} Push Me Push Me
The button on the left is the normal appearance of the pushbutton after Reader/Acrobat
has supplied its appearance, the “button” on the right is how the button would appear
in sumatraPDF, for example, just after PDF creation using pdflatex, xelatex, or lualatex,
or in a DVI previewer after latexing.
There are enhanced previews for other fields that support a \V or \CA key (push-
buttons, text fields, list boxes, combo boxes, check boxes and radio button fields). In
each case, the argument of the key is typeset into the document beneath the field when
\pmpvOn is expanded prior. The arguments of \V and \CA recognize a local command
\tops \tops (\textorpdfstring) to offer an alternate string that is typeset:
real value preview value

\textField[\V{\tops{preview value}{display value}}
\DV{real value}]{topstxt}{1.5in}{13bp}
The field on the left shows how the text field actually appears within Adobe Reader,
and the rectangle on the right is how that same field appears in a non-conforming PDF
reader, such as sumatraPDF. The alias \tops should only be used within the \V and \CA
keys.
For check box and radio button fields, the \tops command is not supported within
the \V key. For these types of fields, the value key is typically a mark: a check,
an cross, a star, and so on. The eforms package defines the declarative command
\pmpvMrk{mrk} that takes one argument mrk, the (preview) mark to be used. The
package declares \pmpvMrk{X}, another good choice is \pmpvMrk{$\checkmark$}.
Final Preparation. In the modern era of LATEX, it is customary by some to use sumatraPDF
or some other non-conforming PDF reader during development; however, you should
always open your final PDF (which was built with \previewOff\pmpvOff) in Adobe
Reader DC (or in Acrobat), save it to obtain the correct appearances of the fields placed
in the document.

b Refer to the article titled eforms: Enhanced Previews for more technical details and
examples; the article is found on the AcroTEX Blog website.
1 Pushbuttons are covered in Section 2.1, beginning on page 8.
7
1.4. The useui option

The useui option includes the xkeyval package, and defines a number of key-value
pairs that are used in the optional arguments of the form fields and links. These key-
value pairs are more “user-friendly” to use. See Section 6, page 30, for a description of
these key-value pairs.
1.5. The unicode option of hyperref

The eforms package will obey the unicode option of hyperref. Whenever this option is
taken in hyperref, for certain keys (namely, \V, \DV, \TU, \CA, \RC, and \AC), standard
latex markup may be used to enter the values of these keys, for example, in a text
field, you might set \V{J\"{u}rgen}. This key-value pair will produce a field value of
“Jürgen” in that text field.
2. Form Fields
The eforms support for PDF forms defines seven basic (and internal) commands for
creating the seven types of form elements. These seven are used as “building blocks”
for defining all buttons, check boxes, radio buttons and text fields used in the exerquiz
quizzes; and for defining seven user-commands: \listBox, \comboBox, \pushButton,
\checkBox, \radioButton, \textField, and \sigField. These user commands are
the topic of the subsequent sections. Note, viewing these form fields outside of Adobe
Reader or Acrobat itself may be a problem, please review the paragraphs on titled
‘The preview option’ on page 5.
Each of the above listed field commands has an optional first parameter that is used
to modify the appearance of the field, and/or to add actions to the field. This is a “local”
capability, i.e., a way of modifying an individual field. There is also a “global” mecha-
nism. Each field type has its own \everyFieldTypeName command. For example, all
buttons created by \pushButton can be modified using the \everyPushButton com-
mand. See the sections on Check Boxes and Radio Buttons for examples and additional
comments.
The local modifications (the ones inserted into the field by the first parameter) are
read after the global modifications, in this way, the local modifications overwrite the
global ones.
Key-value Pairs. The optional first parameter of each of the form and link commands
take two styles of key-values:
1. eforms KVP: This is the key-value system originally developed, each KVP has the
form \key{val}. Through these keys, you can set the appearance of a form or
link, and set the actions as well.
The \presets key is useful for developing collections of pre-defined key-value

pairs for insertion into the optional parameter list. For example,
\def\myFavFive{%
\BC{1 0 0}\BG{0 1 0}\textColor{1 0 0}\Q{2}\CA{Push Me}}
Form Fields 8
Later, a button can be created using these preset values:
\pushButton[\presets{\myFavFive}
\A{\JS{app.alert("AcroTeX rocks!")}}]{pb1}{}{11bp}
The eforms KVP system is explained throughout the manual, a complete listing
of all supported KVPs is found in the Appendices, page 57.
2. xkeyval KVP: When the useui option is taken, key-value pairs are defined of
the form key[=value]. The key-value pairs are actually a value of a special
eforms key, \ui. The value of \ui consists of a comma-delimited list of xkeyval
key-value pairs.
This style of key-value pairs also has a presets key, useful for developing collec-
tions of pre-defined key-value pairs for insertion into the optional parameter list.
For example,
\def\myFavFive{%
bordercolor={1 0 0},bgcolor={0 1 0},
textcolor={1 0 0},align={right},uptxt={Push Me}}
Later, a button can be created using these preset values:
\pushButton[\ui{presets=\myFavFive,
js={app.alert("AcroTeX rocks!")}}]{pb1}{}{11bp}
The xkeyval KVP system is described in ‘The useui option: A User-Friendly Inter-
face’ on page 30.
The first (optional) parameter is read in first, but only after “sanitizing” certain
characters that have special meaning to LATEX, these are ˜, #, and &; each of these may
appear as part of a URL, or may appear in JavaScript code. Within the first parameter,
these three character can be used freely, without escaping them.
2.1. Button Fields

Buttons are form elements that the user interacts with using only a mouse. There are
three types of buttons: pushbuttons, check boxes and radio buttons.
• Pushbutton fields
The pushbutton is a button field that has no value, it is neither on nor off. Generally,
pushbuttons are used to initiate some action, such as JavaScript action.
\pushButton[#1]{#2}{#3}{#4}
Form Fields 9
Parameter Description:
#1: optional, used to enter any modification of appearance/actions
#2: the title of the button field (also called the field name)
#3: the width of the bounding rectangle
#4: the height of the bounding rectangle
Default Appearance: The default appearance of a pushbutton is determined by the

following:
\W{1}\S{B}\F{\FPrint}\BC{0 0 0}
\H{P}\BG{.7529 .7529 .7529}
Key Variables: The first (optional) parameter can be used to modify the default appear-
ance of a button field and to add some actions. Following is a list of the variables used
within the brackets of this optional argument for the pushbutton: \Ff, \F, \H, \TU, \W,
\S, \R, \BC, \BG, \CA, \RC, \AC, \mkIns, \textFont, \textSize, \textColor, \A, \AA
and \rawPDF. See the Support Key Variables table for descriptions and notes on each
of these variables.
☛ If the width argument (#3) is left empty, the LATEX code attempts to determine the appro-
priate width based on the width of the text given by \CA, \RC and \AC. See Example 2,
below.
Global Modification: \everyPushButton{KV-pairs}
Example 1. This example resets all forms in this document: Push
\pushButton[\CA{Push}\AC{Me}\RC{Reset}\A{/S/ResetForm}]
{myButton}{36bp}{12bp}
Example 2. Button with empty width argument: Push
\pushButton[\CA{Push}\AC{Me}\RC{Reset}\A{/S/ResetForm}]
{myButton}{}{12bp}
Refer to the icon-appr package to supply icon appearances to pushbuttons created by

the eforms package.
• Check Boxes
A check box is a type of button that has one of two values, “off” or “on”. The value of
the field when the field is “off” is Off; the value of the “on” state can be defined by the
user.
\checkBox[#1]{#2}{#3}{#4}{#5}
Form Fields 10
#2: the title of the check box button
#5: the name of the “on” state (the export value)
Default Appearance: The default appearance of a standard check box is determined by

the following:
\W{1}\S{S}\BC{0 0 0}\F{\FPrint}
Key Variables: The first (optional) parameter can be used to modify the default ap-
pearance of a check box and to add some actions. Following is a list of the variables
used within the brackets of this optional argument for the check box: \Ff, \F, \TU, \W,
\S, \MK, \DA, \AP, \AS, \R, \textFont, \textSize, \textColor, \DV, \V, \A, \AA and
\rawPDF. See the Supported Key Variables table for descriptions and notes on each of
these variables.
Global Modification: \everyCheckBox{KV-pairs}
Example 3. Are you married? Yes:
\checkBox[\symbolchoice{circle}]{myCheck}{10bp}{10bp}{On}
In the example, the appearance of this check box was modified through the global mod-
ification scheme. The following command appears in the preamble of this document:
\everyCheckBox{
\BC{.690 .769 .871} % border color
\BG{.941 1 .941} % background color
\textColor{1 0 0} % text color
}
Refer to the icon-appr package to supply icon appearances to checkbox buttons created
by the eforms package.
• Radio Buttons
A radio button field is similar to a check box, but is meant to be used in unison with
one or more additional radio buttons.
\radioButton[#1]{#2}{#3}{#4}{#5}
Form Fields 11
#2: the title of the radio button
#5: the name of the “on” state (the export value)

A collection of radio buttons meant to be used in unison need to all have the same
title (parameter #2) but different export values (parameter #5).
Default Appearance: The default appearance of a standard radio button is determined
by the following:
\W{1}\S{S}\BC{0 0 0}\F{\FPrint}
ance of a radio button and to add some actions. Following is a list of the variables used
within the brackets of this optional argument for the radio button: \Ff, \F, \TU, \W,
\S, \MK, \DA, \AP, \AS, \R, \textFont, \textSize, \textColor, \DV, \V, \A, \AA and
these variables.
Global Modification: \everyRadioButton{KV-pairs}
Example 4. What is your gender? Male: Female: Neither:
Male: \radioButton{myRadio}{10bp}{10bp}{Male}
Female: \radioButton{myRadio}{10bp}{10bp}{Female}
Neither: \radioButton[\A{\JS{app.alert("You can’t be ’neither’!
I’m resetting the field, guess again!");\r
this.resetForm(["myRadio"])}}]{myRadio}{10bp}{10bp}{Neither}
In the example, the appearance of these radio button fields was modified through the
global modification scheme. The following command appears in the preamble of this
document:
\everyRadioButton{
\BC{.690 .769 .871} % border color
\BG{.941 1 .941} % background color
\textColor{0 0 1} % text color
\symbolchoice{star} % check symbol
}
Refer to the icon-appr package to supply icon appearances to radio button fields created
by the eforms package.
Form Fields 12
2.2. Choice Fields

A choice field is a list of text items, one or more of which can be selected by the user.
• List Boxes
A scrollable list box is a type of choice field in which several of the choices are visible in
a rectangle. A scroll bar becomes available if any of the items in the list are not visible
in the rectangle provided.
\listBox[#1]{#2}{#3}{#4}{#5}
#2: the title of the list box
#5: an array of appearance/values of list.

The fifth parameter needs more explanation. The value of this parameter which defines
the items in the list—their appearance text and their export values—take two forms:
1. An array of arrays:
[(v1)(item1)][(v2)(item2)]...[(vn)(itemn)]
The first entry in the two member array is the export value of the item, the second
is the appearance text of that item.
2. An array of strings:
(item1)(item2)...(itemn)
In this case, the export value is the same as the appearance text.
Default Appearance: The default appearance of a standard list box is determined by

the following:
\W{1}\S{I}\F{\FPrint}\BC{0 0 0}
Form Fields 13
Key Variables: The first (optional) parameter can be used to modify the default ap-
pearance of a list and to add some actions. Following is a list of the variables used
within the brackets of this optional argument for the list box: \Ff, \F, \TU, \W, \S, \R,
\BC, \BG, \mkIns, \textFont, \textSize, \textColor, \DV, \V, \A and \AA. See the
Supported Key Variables table for descriptions and notes on each of these variables.
\Ff Field flags. Values appropriate to a list box are \FfCommitOnSelChange (com-
mits immediately after selection, PDF 1.5); \FfSort (sorts2 the items); \FfMultiSelect
(allows more than one value to be selected, PDF 1.4). It is important to note that the
flags \FfMultiSelect and \FfCommitOnSelChange cannot both be in effect. See the
Appendix for a complete list of values for the Ff flag.
Global Modification: \everyListBox{KV-pairs}
Example 5. List Box (Version 5.0 Required): Socks
Shoes
\listBox[\autoCenter{n}\DV{1}\V{1} Pants
\BG{0.98 0.92 0.73}\BC{0 .6 0} Shirt
\AA{\AAKeystroke{% Tie
if(!event.willCommit)app.alert(%
"You chose \\"" + event.change\r
+ "\\""+", which has an export value of "
+ event.changeEx);}}]{myList}{1in}{55bp}
{[(1)(Socks)][(2)(Shoes)][(3)(Pants)][(4)(Shirt)][(5)(Tie)]}
• Combo Boxes
A combo box is a drop down list of items that can optionally have an editable text box
for the user to type in a value other than the predefined choices.
\comboBox[#1]{#2}{#3}{#4}{#5}
#2: the title of the combo box
#5: an array of appearance/values of list

The fifth parameter needs more explanation. The value of this parameter which defines
the items in the list—their appearance text and their export values—take two forms:
2 This flag really is not useful unless you have the full Acrobat application, the Sort items check box
is checked in the Options tab of the Fields Properties dialog for the field. Initially, the items are listed in
the same order as listed in the #5 argument; the Acrobat application will sort the list if you view the Fields
Properties for the field and click OK. Be sure to save the changes.
Form Fields 14
1. An array of arrays:
[(v1)(item1)][(v2)(item2)]...[(vn)(itemn)]
The first entry in the two member array is the export value of the item, the second
is the appearance text of that item.
2. An array of strings:
(item1)(item2)...(itemn)
In this case, the export value is the same as the appearance text.
Default Appearance: The default appearance of a standard combo box is determined
by the following:
\W{1}\S{I}\F{\FPrint}\BC{0 0 0}
ance of a list and to add some actions. Following is a list of the variables used within
the brackets of this optional argument for the list box: \Ff, \F, \TU, \W, \S, \R, \BC,
\BG, \mkIns, \textFont, \textSize, \textColor, \DV and \V, \A and \AA. See the
Support Key Variables table for descriptions and notes on each of these variables.
\Ff Field flags. Values appropriate to a combo box are \FfEdit (allows the user to
type in a choice); \FfDoNotSpellCheck (turn spell check off, applicable only if \FfEdit
is set); \FfCommitOnSelChange (commits immediately after selection); and \FfSort
(sorts the items, see footnote 2, page 13). See the Appendix for a complete list of
values for the Ff flag.
Global Modification: \everyComboBox{KV-pairs}
Example 6. Editable combo box (Version 5.0): Socks Get
\comboBox[\Ff\FfEdit\DV{1}\V{1}
\BG{0.98 0.92 0.73}\BC{0 .6 0}]{myCombo}{1in}{11bp}
{[(1)(Socks)][(2)(Shoes)][(3)(Pants)][(4)(Shirt)][(5)(Tie)]}\kern1bp%
% Follow up with a pushbutton
\pushButton[\BC{0 .6 0}\CA{Get}\AC{Combo}\RC{Box}\A{\JS{\getComboJS}}]
{myComboButton}{33bp}{11bp}
The JavaScript action for the button is given below:
\begin{defineJS}{\getComboJS}
var f = this.getField("myCombo");
var a = f.currentValueIndices;
if ( a == -1 )
app.alert("You’ve typed in \\"" + f.value +"\\".");
else
app.alert("Selection: " + f.getItemAt(a, false)
+ " (export value: " + f.getItemAt(a, true)+").");
\end{defineJS}
Form Fields 15
2.3. Text Fields

A text field is the way a user can enter text into a form.
\textField[#1]{#2}{#3}{#4}
#2: the title of the text field
Default Appearance: The default appearance of a standard text field is determined by
the following:
\F{\FPrint}\BC{0 0 0}\W{1}\S{S}
ance of a text field and to add some actions. Following is a list of the variables used
within the brackets of this optional argument for the text field: \Ff, \F, \TU, \Q, \W,
\S, \MaxLen, \R, \BC, \BG, \mkIns, \textFont, \textSize, \textColor, \DV, \V, \A,
\AA and \rawPDF. See the Supported Key Variables table for descriptions and notes on
each of these variables.
\Ff Field flags. There are several values appropriate to a text field: \FfMultiline
(create a multiline text field); \FfPassword (create a password field); \FfFileSelect
(select a file from the local hard drive as the value of the text field, PDF 1.4); \FfComb (if
set, the text field becomes a comb field, the number of combs is determined by the value
of \MaxLen, PDF 1.5); \FfDoNotSpellCheck (automatic spell check is not performed,
PDF 1.4); \FfDoNotScroll (disable the scrolling of long text, this limits the amount of
text that can be entered to the width of the text field provided, PDF 1.4); \FfRichText
(allows rich text to be entered into the text field, PDF 1.5).
Global Modification: \everyTextField{KV-pairs}
Example 7. Enter Name:
\textField
[\BC{0 0 1}\BG{0.98 0.92 0.73}
\textColor{1 0 0}
]{myText}{1.5in}{12bp}
Example 8. An example of a calculation using a Calculate script. (Calculate works cor-
rectly with drivers dvips, dvipsone, or dvipdfm are used.)
Number 1:
Number 2:
Total:
Form Fields 16
The listing for this list of three text fields is
\textField[\AA{%
\AAKeystroke{AFNumber_Keystroke(1,1,0,0,"",true)}
\AAFormat{AFNumber_Format(1,1,0,0,"",true)}}
]{num.1}{1in}{11bp}
\textField[\AA{%
\AAFormat{AFNumber_Format(1,1,0,0,"",true)}}
]{num.2}{1in}{11bp}
\textField[\AA{%
\AAFormat{AFNumber_Format(1,1,0,0,"",true)}
\AACalculate{AFSimple_Calculate("SUM", new Array("num"))}
]{sum}{1in}{11bp}
2.4. Signature Fields

A signature field is a field that can be digitally signed.
\sigField[#1]{#2}{#3}{#4}
#2: the title of the signature field
Default Appearance: The default appearance of a standard signature field is deter-

mined by the following:
\F{\FPrint}\BC{}\BG{}\W{1}\S{S}
ance of a signature field and to add some actions. Following is a list of the variables
used within the brackets of this optional argument for the signature field: \F, \TU, \W,
\S, \R, \Lock, \BC, \BG, \mkIns, \textFont, \textSize, \textColor, \DV, \A, \AA and
these variables.
Global Modification: \everySigField{KV-pairs}
Form Fields 17
Example 9. Sign here:
\sigField[\BC{0 0 0}]
{mySig}{2in}{4\baselineskip}
To sign this field, use the Acrobat user interface, or use the package aeb_pro, and the
following docassembly code:
\begin{docassembly}
\signInfo{
cSigFieldName: "mySig", ohandler: security.PPKLiteHandler,
cert: "D_P_Story.pfx", password: "dps017",
oInfo: { location: "Niceville, FL",
reason: "I am approving this document",
contactInfo: "[email protected]",
appearance: "My Signature" }
};
\signatureSign
\end{docassembly}
• cSigFieldName is the name of the field to be signed.
• ohandler is the name of the security handler to be used to sign the field, usu-
ally, this is security.PPKLiteHandler; security.PPKLiteHandler is used if
ohandler is not listed in the property list.
• cert is the name of the Digital ID certificate file to be used. The extension for
this file is .pfx (Windows) and .p12 (Mac OS). These files reside in the folder,
app.getPath( {cCategory:"user"})/Security
However, just enter the file name, such as cert: "D_P_Story.pfx".
• password: The Digital ID requires a password to access and to use. For example:
password: "dps017".
• oInfo is a JavaScript object with various properties to be filled in, location,

reason, contactInfo, and appearance. The appearance is important, through
it, you can choose a particular appearance for the digital signature, including a cus-
tom signature that you’ve created. In the example above, we have appearance:
"My Signature". My Signature is the name I’ve given a particular digital ID of
mine. If the appearance property is not included in oInfo, Acrobat will use the
one named "Standard Text".
Important: Additional information on signatures can be found at the Acrobat Developer

Center; or go to the Security page; in particular, see the document Digital Signature User
Guide for Acrobat 9.0 and Adobe Reader 9.0. Other comments on the topic of signature
fields:
18
• The open key \textSize is recognized, but is change to 0.
• The Signed tab of the Digital Signatures Properties dialog box, lists an entry titled
“This script executes when the field is signed.” This JavaScript is implemented
through the format script of the AA key. Thus,
\AA{\AAFormat{console.println("Signed!");}}
places message in the console when the field is signed.
• The \Lock key can be used to lock various fields when the document is signed.
1 \Lock{/Action/All}
2 \Lock{/Action/Include/Fields [(field1)(field2)...]}
3 \Lock{/Action/Exclude/Fields [(field1)(field2)...]}
– In (1), all fields are locked when the signature field is signed.
– In (2), only the listed fields are locked when the signature field is signed.
– In (3), all fields, except the ones listed, are locked when the signature field is
signed.
The /Fields key is required when the action is either /Include or /Exclude.
3. Link Annotations
The eforms package has several link commands that are sufficiently general that they
can be given arbitrary appearances, and can perform a wide range of actions.
The borders of the link commands can be controlled through optional parameter,
their default appearance follow the same pattern of hyperref: If the colorlinks option
is used (in hyperref) then the border is invisible by default; otherwise, there is a visible
border.
When the colorlinks option is chosen (in hyperref), the link text is colored using
the command \defaultlinkcolor, this is a named color. \defaultlinkcolor has a
definition of
\newcommand{\defaultlinkcolor}{\@linkcolor}
where \@linkcolor is a command defined in hyperref, and is defined to be red. This
can be redefined as desired.3
The first link command is a general link for text, or any LATEX content. It is used, for
example, by the aeb_mlink package to create multiple-line links.
\setLink[options]{link_text}
\setLinkText[options]{link_text}
Both link commands are the same, the use of the second one, \setLinkText (grayed
out), is discouraged in favor of the use of \setLink.
3 The Web package redefines \@linkcolor to be a flavor of green.
19
Parameter Description: The command has two arguments, the first is optional. The
first parameter takes key-value pairs to change appearance and define actions. The
default appearance of this link is \S{S}\Border{0 0 0}, an invisible yet solid border
line. (The visibility of the border is actually controlled by the colorlinks option of
hyperref, as explained above.) The second parameter is the link text. This argument
does not have to be text, it can be anything that takes up space, such as a graphic or
\parbox.
Example 10. Push me!
\setLink[\A{\JS{app.alert("AcroTeX rocks!")}}
\linktxtcolor{blue}\Color{0 0 1}\W1\S{U}\H{P}]{Push me!}

b Additional examples of \setLink may be found in the rather comprehensive article
Support for Links in AeB/eForms, aeb_links.pdf, found on the AcroTEX Blog website.
The next link command is a convenience command to put the link content into a
parbox, the parameters enable you to set the width, height and position of material in
the box.
\setLinkBbox[options]{width}{height}
[position]{link_content}
Parameter Description: The command has five arguments, the first is optional.
options are optional key-value pairs to change the appearance or action of this
link.
width is the width of the \parbox.
height is the height of the \parbox.
position is the positioning parameter of the \parbox (b, c, t).
link_content is the text or object to be enclosed in a \parbox
Example 11. Press Me!
\setLinkBbox[\W{1}\Color{1 0 0}
\A{\JS{app.alert("Thank you for using AcroTeX!")}}
]{50bp}{30bp}[c]{\centering Press Me!}
4. Actions
A form field may simply gather data from the user; additionally, it may perform one
or more actions. Actions include execute JavaScript code, going to a particular page
in a document, open a file, execute a menu item, reset a form, play media or a sound,
Actions 20
and so on. Beginning with Acrobat 5.0, most actions can be performed using JavaScript
methods.
An action is initiated by a trigger, a field may have many actions, each with a separate
trigger. The different triggers are discussed in Trigger Events, and the various types of
actions available are covered in the section Action Types.
4.1. Trigger Events

Event actions are initiated by triggers. For fields, there are ten different triggers.
1. Mouse Enter: The event is triggered when mouse enters the region defined by the
bounding rectangle. The \AAMouseEnter key is used within the argument of \AA
to define a mouse enter event:
\textField[\AA{\AAMouseEnter{%
\JS{app.alert("You’ve entered my text field, get out!")}}}]
{myText}{1.5in}{12bp}
2. Mouse Exit: The event is triggered when mouse exits the region defined by the
bounding rectangle. The \AAMouseExit key is used within the argument \AA to
define a mouse exit event:
\textField[\AA{\AAMouseExit{%
\JS{app.alert("You’ve exited my domain, never return!")}}}]
3. Mouse Down: The event is triggered when the (left) mouse button is pushed down
while the mouse is within the bounding rectangle of the field. The \AAMouseDown
key is used within the argument of \AA to define a mouse down event:
\pushButton[\AA{\AAMouseDown{\JS{app.alert("Mouse Down!")}}}]
4. Mouse Up: The event is triggered when the (left) mouse button is released while
the mouse is within the bounding rectangle of the field. The \A key (or \AAMouseUp
key is used within the argument of \AA) is used to define a mouse up event:
\pushButton[\A{\JS{app.alert("Mouse Up!")}}]
The same code can be performed as follows:
\pushButton[\AA{\AAMouseUp{\JS{app.alert("Mouse Up!")}}}]
When both types of mouse up actions are defined for the same field, the one defined
by \A is the one that is executed.
5. On Focus: The event is triggered when the field comes into focus (either by tab-
bing from another field, or clicking the mouse within the bounding rectangle. The
\AAOnFocus key is used within the argument of \AA to define an ‘on focus’ event:
Actions 21
\textField[\AA{\AAOnFocus{\JS{%
app.alert("Please enter some data!")}}}]
6. On Blur: The event is triggered when the field loses focus (either by tabbing to
another field, by clicking somewhere outside the field, or (in the case of a text field,
for example) pressing the Enter button. The \AAOnBlur key is used within the
argument of \AA to define an ‘on blur’ event:
\textField[\AA{\AAOnBlur{%
\JS{app.alert("Thanks for the data, I think!")}}}]
7. Format: The format event is the event that occurs when text is entered into a text
or combo box; during this event, optionally defined JavaScript code is executed
to format the appearance of the text within the field. The \AAFormat key is used
within the argument of \AA to define a format event:
\textField[\AA{%
\AAKeystroke{AFNumber_Keystroke(2,0,1,0,"\\u0024",true);}
\AAFormat{AFNumber_Format(2,0,1,0,"\\u0024",true);}}]
The above example creates a text field which will accept only a number into it and
which will format the number into U.S. currency.
8. Keystroke: This keystroke event is the event that occurs when individual keystroke
is entered into a choice field (list or combo) or a text field; during this event, option-
ally defined JavaScript can be used to process the keystroke. The \AAKeystroke
key is used within the argument of \AA to define a keystroke event; see the format
example above.
9. Validate: The validate event is an event for which JavaScript code can be defined to
validate the data that has been entered (text and combo fields only). The \AAVali-
date key is used within the argument of \AA to define a validate event:
\textField[\AA{%
\AAFormat{AFNumber_Format(2,0,1,0,"\\u0024",true);}
\AAValidate{%
if (event.value > 1000 || event.value < -1000) {\r\t
app.alert("Invalid value, rejecting your value!");\r\t
event.rc = false;\r
}}
}]{myText}{1.5in}{12bp}
10. Calculate: The calculate event is an event for which JavaScript code can be defined
to make automatic calculations based on entries of one or more fields (text and
combo fields only). The \AACalculate key is used within the argument of \AA to
define a calculate event:
Actions 22
\textField[\AA{%
\AAFormat{AFNumber_Format(2,0,1,0,"\\u0024",true);}
\AACalculate{AFSimple_Calculate("SUM",new Array("Prices"));}
}]{myText}{1.5in}{12bp}
11. PageOpen: (The PO key, Table 8.10, PDF 1.5) An action to be performed when the
page containing the annotation is opened (for example, when the user navigates to
it from the next or previous page or by means of a link annotation or outline item).
The action is executed after the page’s open action. The \AAPageOpen key is used
within the argument of \AA to define an annotation page open event:
12. PageClose: (The PC key, Table 8.10, PDF 1.5) An action to be performed when the
page containing the annotation is closed (for example, when the user navigates to
the next or previous page, or follows a link annotation or outline item). The action
is executed before the page’s close action. \AAPageClose key is used within the
argument of \AA to define an annotation page close event.
13. PageVisible: (The PV key, Table 8.10, PDF 1.5) An action to be performed when
the page containing the annotation becomes visible in the viewer application’s user
interface. \AAPageVisible key is used within the argument of \AA to define an
annotation page visible event.
14. PageInvisible: (The PI key, Table 8.10, PDF 1.5) An action to be performed when the
page containing the annotation is no longer visible in the viewer application’s user
interface. \AAPageInvisible key is used within the argument of \AA to define an
annotation page invisible event.
Below is a simple example of usage. The actions write to the console.
\textField[\AA{%
\AAPageOpen{console.println("Page \thepage: PO");}
\AAPageClose{console.println("Page \thepage: PC");}
\AAPageVisible{console.println("Page \thepage: PV");}
\AAPageInvisible{console.println("Page \thepage: PI");}
}]{tf\thepage}{2in}{11bp}
}
Additional examples appear in the file eqforms.tex.
4.2. Action Types

The following is only a partial listing of the action types, as given in Table 8.36 of the
PDF Reference [5]. The entire list and the details of usage can be obtained from the PDF
Reference.
Actions 23
Action Type Description

GoTo Go to a destination in the current document
GoToR Go to a destination in another document
Launch Launch an application, usually to open a file
URI Resolve a uniform resource identifier
Named Execute an action predefined by the viewer
SubmitForm Send data to a uniform resource locator
JavaScript Execute a JavaScript script (PDF 1.3)
Examples of each type of action follow.

GoTo: Go to a (named or explicit) destination within the current document. In this
example, we ‘go to’ the named destination toc.1, which references the table of contents
pages. This button goes to a named destination: Go
\pushButton[\CA{Go}\AC{Now!}\RC{to TOC}
\A{/S/GoTo/D(toc.1)}]{myButton1}{}{10bp}
For a named destination, the value of the /D key is a string, (toc.1) in the above
example, that specifies the destination name.
The following is an example of an explicit destination: Go
\pushButton[\CA{Go}\AC{Now!}\RC{to Page 3}
\A{/S/GoTo/D[{Page3}/Fit]}]{myButton1}{}{10bp}
The value of the destination key /D is an array referencing a page number ({Page3})
and a view (/Fit).
For a GoTo action, the first entry in the destination array, {Page3}, is an indirect
reference to a page, the notation {Page3} is understood by the distiller. For dvipdfm,
use the @page primitive:
\makeatletter\def\Page#1{@page#1}\makeatother
\A{/S/GoTo/D[\Page3/Fit]}]{myButton1}{}{10bp}
pdftex has no mechanism for inserting indirect page references.

See section 8.5.3, ‘Go-To Actions’, of the PDF Reference [5] for details of the syntax
of GoTo, and section 8.2.1 for documentation on explicit and named destinations.
GoToR: Go to a (named or explicit) destination in a remote document. In this example,
we ‘go to a remote’ destination, a named destination in another document. Go
\A{/S/GoToR/F(webeqtst.pdf)/D(webtoc)]{myButton2}{}{10bp}
This example illustrates an explicit destination; the following button jumps to page 3 in
another document: Go
\A{/S/GoToR/F(webeqtst.pdf)/D[2/Fit]}]{myButton2}{}{10bp}
Actions 24
The value of the destination key /D is an array referencing a page number and a view
(/Fit).
For an explicit destination, the PDF Reference [5] specifies that the first entry in the
destination array should be a page number (as contrasted with an indirect reference
to a page number, for the case of GoTo). The destination, /D[2/Fit] would correctly
work for distiller, dvipdfm and pdftex.
See section 8.5.3, ‘Remote Go-To Actions’, of the PDF Reference [5] for details of the
syntax of GoToR, and section 8.2.1 for documentation on explicit and named destina-
tions.
Launch: Launch an application (‘Open a file’). In this example, we open a TEX file
using the application associated with the .tex extension: Go
\A{/S/Launch/F(webeqtst.tex)}]{myButton3}{}{10bp}
See section 8.5.3, ‘Launch Actions’, of the PDF Reference [5] for details of the syntax.
URI: Open a web link. In this example, we go to the Adobe web site: Go
\pushButton[\CA{Go}\AC{Adobe!}\RC{To}
\A{/S/URI/URI(http://www.adobe.com/)}]{myButton4}{}{10bp}
See section 8.5.3, ‘URI Actions’, of the PDF Reference [5] for details of the syntax.
Acrobat (Adobe Reader) also support open parameters, using these key-value pairs,
we can go to a specific page in a PDF on the web, and even search for words, for example
Go & Search opens the AeB Manual on the Internet, goes to page 8, and searches for the
words AcroTeX, web, and exerquiz.
\pushButton[\CA{Go & Search}

\A{/S/URI/URI(http://www.math.uakron.edu/˜dpstory/
acrotex/aeb_man.pdf#page=8&search=AcroTeX web exerquiz)}]
{myButton4a}{}{10bp}
The same can be accomplished using \setLink.

Named: Execute a ‘named’ action (i.e., a menu item). Named actions listed in the
PDF Reference are NextPage, PrevPage, FirstPage and LastPage. A complete list of
named actions can be obtained by executing the code app.listMenuItems() in the
JavaScript console of Acrobat (Pro). Go
\pushButton[\CA{Go}\AC{Previous!}\RC{To}
\A{/S/Named/N/PrevPage}]{myButton5}{}{10bp}
See section 8.5.3, ‘Named Actions,’ of the PDF Reference [5] for details of the syntax.
The named actions listed in the PDF Reference are NextPage, PrevPage, FirstPage,
and LastPage.
In theory, any menu item can be executed as a named actions; there are several
factors to be taken into consideration: (1) Not all menu items available to Acrobat are
listed on the menu bar of Adobe Reader, when choosing a name event to use, you should
Actions 25
decide if the application executing the named action supports that action; (2) In recent
versions, starting with version 7, there have been security restrictions on the execution
of menu items, the so-called “white list.” Only named actions listed on the white list
are allowed to execute. The white list for version 8.0 is
Named Actions on Whitelist

AcroSendMail:SendMail LastPage ShowHideToolbarCommenting
ActualSize NextPage ShowHideToolbarData
AddFileAttachment OneColumn ShowHideToolbarEdit
BookmarkShowLocation OpenOrganizer ShowHideToolbarEditing
Close PageSetup ShowHideToolbarFile
CropPages PrevPage ShowHideToolbarFind
DeletePages Print ShowHideToolbarForms
ExtractPages PropertyToolbar ShowHideToolbarMeasuring
Find Quit ShowHideToolbarNavigation
FindCurrentBookmark ReplacePages ShowHideToolbarPageDisplay
FindSearch RotatePages ShowHideToolbarPrintProduction
FirstPage SaveAs ShowHideToolbarRedaction
FitHeight Scan ShowHideToolbarTasks
FitPage ShowHideAnnotManager ShowHideToolbarTypewriter
FitVisible ShowHideArticles SinglePage
FitWidth ShowHideBookmarks Spelling
FullScreen ShowHideFields Spelling:Check
GeneralInfo ShowHideFileAttachment TwoColumns
GeneralPrefs ShowHideModelTree TwoPages
GoBack ShowHideOptCont Web2PDF:OpenURL
GoForward ShowHideSignatures ZoomTo
GoToPage ShowHideThumbnails ZoomViewIn
InsertPages ShowHideToolbarBasicTools ZoomViewOut
In addition to the Whitelist for version 8, the following menu items are added for
version 9.
Named Actions on Whitelist

Annots:Tool:InkMenuItem CollectionShowRoot HandMenuItem
CollectionDetails DocHelpUserGuide HelpReader
CollectionHome GoBackDoc rolReadPage
CollectionPreview GoForwardDoc ZoomDragMenuItem
As mentioned before, some of these are for Acrobat only, others are available for Adobe
Reader. I’ll let you sort them out. If you try to execute a named action that is not on
the white list, the action will silently fail.
SubmitForm: Submit forms Action. In this example, we submit a URL to a CGI, which
then sends the requested file back to the browser:
Homepage of D. P. Story Go!
Note: This script no longer works, server-side scripting at the uakron.edu server is no
longer permitted (for security reasons). The verbatim lisiting of the code as it used to
26
be when it worked.
\definePath{\URL}{http://www.math.uakron.edu/˜dpstory}
\comboBox[\DV{\URL}\V{\URL}\BG{webyellow}\BC{webgreen}]
{dest}{1.75in}{11bp}{%
[(\URL)( Homepage of D. P. Story)]
[(\URL/acrotex.html)( AcroTeX Homepage)]
[(\URL/webeq.html)( AcroTeX Bundle)]
[(\URL/acrotex/examples/webeqtst.pdf)(Exerquiz Demo file {(PDF)})]
}\kern1bp\pushButton[\BC{webgreen}\CA{Go!}
\A{/S/SubmitForm/F(http://www.math.uakron.edu/cgi-bin/nph-cgiwrap/%
dpstory/scripts/nph-redir.cgi)/Fields[(dest)]/Flags 4}]
{redirect}{33bp}{11bp}
See section 8.6.4 of the PDF Reference [5] for details of the syntax for ‘Submit Actions’.
JavaScript: Execute a JavaScript action. This is perhaps the most important type
of action. In this example, the previous example is duplicated using the Doc.getURL()
method, we don’t need to submit to a CGI.
Homepage of D. P. Story Go!
\definePath{\URL}{http://www.math.uakron.edu/˜dpstory}
\comboBox[\DV{\URL}\V{\URL}\BG{webyellow}\BC{webgreen}]
{dest}{1.75in}{11bp}{%
[(\URL)( Homepage of D. P. Story)]
[(\URL/acrotex.html)( AcroTeX Homepage)]
[(\URL/webeq.html)( AcroTeX Bundle)]
[(\URL/acrotex/examples/webeqtst.pdf)(Exerquiz Demo file {(PDF)})]
}\kern1bp\pushButton[\BC{webgreen}\CA{Go!}
\A{\JS{%
var f = this.getField("dest");\r
app.launchURL(f.value,false);
}}]{redirect}{33bp}{11bp}
Note the use of the convenience command \JS, defined in the insldjs package, it ex-
pands to the correct syntax: /S/JavaScript/JS(#1), where #1 is the argument of
\JS.
Most all actions can be performed using JavaScript, the reader is referred to the
JavaScript for Acrobat API Reference [4].
5. JavaScript
Acrobat JavaScript is the cross-platform scripting language of the Acrobat suite of prod-
ucts. For Acrobat 5.0 or later, Acrobat JavaScript based on JavaScript version 1.5 of
ISO-16262 (formerly known as ECMAScript), and adds extensions to the core language
to manipulate Acrobat forms, pages, documents, and even the viewer application.
Web-based references to core JavaScript are the Core JavaScript Guide [1] and the
Core JavaScript Reference [2]. For Acrobat JavaScript, we refer you to the Developing Ac-
robat Applications using JavaScript [3] and the JavaScript for Acrobat API Reference [4].
JavaScript 27
5.1. Support of JavaScript

The AcroTEX eDucation Bundle has extensive support for JavaScript, not only for Java-
Script executed in response to a field trigger, but for document level and open page
actions as well. As the topic of this document is eForm support, the reader is referred
to the documentation in the insdljs package, which is distributed with the AcroTEX Bun-
dle.
• The Convenience Command \JS

The syntax for writing JavaScript actions is
\pushButton[\A{/S/JavaScript/JS(script)}]
{jsEx}{22bp}{11bp}
Notice the code is enclosed in matching parentheses. As noted earlier, AcroTEX defines
the command \JS as a convenience for this very common actions; the above example
becomes:
\pushButton[\A{\JS{script}}]{jsEx}{22bp}{11bp}
The code is now enclosed in matching braces.
• Inserting Simple JavaScript

Actions are introduced into a field command through its optional first parameter. Java-
Script actions, in particular, can be inserted by a mouse up4 action, for example, using
the \A and \JS commands.
The “environment” for entering JavaScript is not a verbatim environment: ‘\’ is the
usual TEX escape character and expandable commands are expanded; active characters
are expanded (which is usually not what you want); and primitive commands appear
verbatim (so you can use, for example, ‘{’ and ‘}). Within the optional argument, the
macro \makeJSspecials, which can be redefined, is expanded; the macro makes sev-
eral special definitions: (1) it defines \\ to be ‘\\’; (2) defines \r to be the JavaScript
escape sequence for new line; and (3) defines \t to be the JavaScript escape sequence
for tab.
Example 12. Sum
The verbatim listing for this button is
\pushButton[\CA{Sum}\A{\JS{%
var n = app.response("Enter a positive integer",
"Summing the first \\"n\\" integers");\r
if ( n != null ) {\r\t
var sum = 0;\r\t
for ( var i=1; i <= n; i++ ) {\r\t\t
sum += i;\r\t
}\r
app.alert("The sum of the first n = " + n
4 Other types of possible actions are discussed and illustrated in ‘Actions’ on page 19.
JavaScript 28
+ " integers is " + sum + ".", 3);

}
}}]{jsSum}{22bp}{11bp}
Code Comments. Within the JavaScript string, we want literal double quotes ", to avoid
" being interpreted as the end of the string (or the beginning of a string) we have to
double escape the double quotes, as in \\". (This is not necessary when entering code
in the JavaScript editor if you have the Acrobat application.) I try to write JavaScript that
I can easily read, edit, and debug in the JavaScript editor (available in the full Acrobat
application); for this reason, I’ve added in new lines and tabbing (\r and \t). Many
people, however, have only the Adobe Reader and cannot see their code to debug it; in
this case, the formatting is really not needed.
Needless to say, the following sample will not compile because we do not have matching
braces.
\pushButton[\A{\JS{var x = "{"}}]{jsBrace}{22bp}{11bp}
The work around here is
\pushButton[\A{\JS{var x = "\jslit\{"}}]{jsBrace}{22bp}{11bp}
In the above work about, the \jslit command (for JavaScript literal) is used. This
command is defined only within the optional arguments of a form field. The definition
of \jslit is \let\jslit\string
• Inserting Complex or Lengthy JavaScript

For JavaScript that is more complex or lengthy, the insdljs Package, distributed with the
AcroTEX Bundle, has the verbatim defineJS environment. Details and idiosyncracies
of this environment are documented in ‘The defineJS Environment’ on page 53. The
example given in Example 6 will suffice; the verbatim listing is reproduced here for
convenience.
First, we define the JavaScript action and name it \getComboJS for the button (prior
to defining the field, possibly in the preamble, or in style files):
\begin{defineJS}{\getComboJS}
if ( a == -1 )
app.alert("You’ve typed in \\"" + f.value +"\\".");
else
app.alert("Selection: " + f.getItemAt(a, false)
+ " (export value: " + f.getItemAt(a, true)+").");
\end{defineJS}
There is no need for the \r and \t commands to format the JavaScript; the environment
obeys lines and spaces; contrast this example with Example 12, page 27.
Now we can define our fields, a combo box (not shown) and button, in this example.
It is the button that uses the JavaScript defined above.
JavaScript 29
\pushButton[\BC{0 .6 0}\CA{Get}\AC{Combo}\RC{Box}
\A{\JS{\getComboJS}}]{myComboButton}{33bp}{11bp}
Within the argument of \JS we insert the macro command, \JS{\getComboJS} for our
JavaScript defined earlier in the defineJS environment

b The demo file aeb_links.pdf, with source attached, is found on the AcroTEX Blog
website.
5.2. Defining JavaScript Strings with \defineJSStr

The command \defineJSStr is used to define JavaScript strings, such as in dialog
boxes. The syntax for this command is
\defineJSStr{\CMD}{JS_string}
Parameter Description: Where \CMD is a command to be defined by \defineJSStr,

for example, \myMessage, and JS_string is the JavaScript string to be defined as
the expansion of the \CMD.
Command Description: \defineJSStr executes \xdef#1{"#2"}, so the JavaScript
is expanded at the time of definition. (Note the enclosing double quotes) Before the
expansion occurs, however, there are a number of definitions that occur locally:
• \uXXXX is recognized as a unicode escape sequence. So, within the JavaScript

string, unicode can be entered directly, for example, \u00FC is the u-umlaut.
• Backslash is still the tex escape character, so any commands in the JavaScript
string get expanded. You can delay the expansion by using \protect. Expansion
occurs when the tex compiler actually expands \CMD.
• \r (carriage return), \n (line feed) and, \t (tab) can be used to format the message,
as desired.
• Use the \cs command to write a word containing a literal backslash in it; for
example, to get \LaTeX to appear in a JavaScript string, you must type \cs{LaTeX}
in the JavaScript string.
• The JavaScript string is enclosed in double quotes ("), if you want a literal double
quote, use \\" to get a literal double quote to appear in a JavaScript string. For
example,
\defineJSStr{\myMessage}
{My name is \\"Stan\\" and I’m \\"the man.\\"}
• The command \jslit is recognized within the JavaScript string. Using \jslit
(short for JavaScript literal), you can insert, for example, unbalanced braces:
\defineJSStr{\myMessage}
{You forgot the left brace \\"\jslit\{\\",
please insert it.}
30
The definition of \jslit is \let\jslit\string.

The design decision to automatically insert the double quotes in the definition of the
string has its faults. When you want to break the string to insert dynamic content,
you must always be aware of the definition \xdef#1{"#2"} contained with the defi-
nition of \defineJSStr. To illustrate, we return to an earlier example presented in
Inserting Complex or Lengthy JavaScript, on page 28.
We begin by defining some JavaScript strings. Note that in each of these two defini-
tions, the leading and trailing double quote (") is missing (these are the ones inserted
automatically). The definitions look a bit strange because we break the string to insert
dynamic content (f.value, f.getItemAt(a, false), etc.), then continue on with the
string from there.
\defineJSStr\myAlerti{You’ve typed in \\"" + f.value +"\\".}
\defineJSStr\myAlertii{Selection: " + f.getItemAt(a, false)
+ " (export value: " + f.getItemAt(a, true)+").}
We use the defineJS environment, after setting the escape code to @. The defineJS is
a fully verbatim environment, the escape character cannot be changed to \, but it may
be changed to another character, such as @.
\begin{defineJS}[\catcode‘\@=0\relax]{\getComboJS}
if ( a == -1 )
app.alert(@myAlerti);
else
app.alert(@myAlertii);
\end{defineJS}
Then again, the use of \defineJSStr is not required, it is a convenience for creat-
ing JavaScript strings, especially ones with embedded Unicode. The previous example
could have been done by defining \myAlerti and \myAlertii by
\newcommand\myAlerti{"You’ve typed in \\"" + f.value +"\\"."}
\newcommand\myAlertii{"Selection: " + f.getItemAt(a, false)
+ " (export value: " + f.getItemAt(a, true)+")."}
Note the presence of the leading and trailing double quotes.
6. The useui option: A User-Friendly Interface

To use the “user-friendly” interface, the useui option must be taken. The key-value
pairs described below are enclosed as the argument of the special \ui key. For example,
\pushButton[\ui{%
textcolor={1 0 0},align={right},
uptxt={Push Me},
js={app.alert("AcroTeX rocks!")}
}]{pb1}{}{11bp}
The useui option: A User-Friendly Interface 31
You can develop your own set of appearances and use the presets key to conveniently
set these. For example,
\def\myFavFive{%
textcolor={1 0 0},align={right},
uptxt={Push Me}
}
Later, a pushbutton can use this preset, like so,
\pushButton[\ui{presets=\myFavFive,
js={app.alert("AcroTeX rocks!")}}]{pb1}{}{11bp}
5
which produces Push Me
You can mix your \myFavFive with different key-value pairs, such as a JavaScript action.
☛ In each of the subsequent subsections, the eforms key to its user-friendly counterpart
is displayed in the margin. Some of the user-friendly are a combination of eforms KVs
and are not represented in the margin in this case.
6.1. The Appearance Tab

We present these key-value pairs to model the user-interface of Acrobat.
border=visible|invisible
Command Description: Used with link annotations and determines whether the border
surrounding the bounding box of the link is visible. In the case of a link, this is the Link
Type: Visible Rectangle or Invisible Rectangle. If you set border equal to invisible,
that will set border line width to zero \W{0}. For forms, this key has no counterpart in
the user interface.
If this key is not specified, the eforms follows the rule: If colorlinks option of hy-
perref is used, the border is invisible; otherwise, it is visible (and the default linewidth
is 1). Use the border key to override this behavior.
\W linewidth=thin|medium|thick
Command Description: The linewidth of the border around a link or a form. The
user interface choices are thin, medium, and thick. This key-value is ignored if the
document author has set the border to invisible.
\H highlight=none|invert|outline|inset|push
Command Description: The highlight type for links and forms, choices are none,
invert, outline, inset and push. The term inset is used with links, and push is
used with forms. They each have the same key value pair.
5 The reader is reminded once again that the author has no understanding of colors.
\BC (forms) or
bordercolor=numnumnum
\Color (links)
Command Description: The color of the border, when visible, in RGB color space. For
example, bordercolor=1 0 0, is the color red.
\S linestyle=solid|dashed|underlined|beveled|inset
Command Description: The line style of the border, possible values are solid,dashed,
underlined, beveled,and inset. Links do not support the beveled option.
\D dasharray=num[num]
Command Description: When a line style of dashed is chosen, you can specify a dash
array. The default is 3.0, which means a repeating pattern of 3 points of line, followed
by 3 points of space. A value of dasharray=3 2 means three points of line, followed
by two points of space. When this key is used without a value, the value is 3.0. When
the dashed key is not present, 3.0 is used.
linktxtcolor
\linktxtcolor linktxtcolor=named_color
Command Description: Set the color of the link text. Ignored if the colorlinks op-
tion of hyperref has not been taken. The value of linktxtcolor is a named color.
For example, linktxtcolor=red. The default is \@linkcolor from hyperref. This de-
fault can be changed by redefining \@linkcolor, or redefining \defaultlinkcolor. If
linktxtcolor={} (an empty argument), or simply linktxtcolor, no color is applied
to the text, the color of the text will be whatever the current color is.
\F annotflags=hidden|print|-print|noview|lock
Command Description: This is a bit field, possible values are hidden, print, -print,
noview, and lock. Multiple values can be specified. The values are “or-ed” together.
Most all forms are printable by default. If you don’t want a form field to print specify
-print. For example, annotflags={-print,lock} makes the field not printable and
is locked, so the field cannot be moved through the UI.
\Ff fieldflags=readonly|required|noexport|multiline|password|
notoggleoff|radio|pushbutton|combo|edit|
sort|fileselect|multiselect|nospellcheck|
noscrolling|comb|radiosinunison|commitonchange|
richtext
Command Description: There are a large number of field flags (Ff) that set a number
of properties of a field. This is a multiple-selection key as well. The values are “or-ed”
together.
Normally, a document author would not specify radio, pushbutton or combo. These
properties are used by eforms to construct a radio button field, a pushbutton and a
combo box. The others can be used as appropriate.
\MaxLen maxlength=num
Command Description: Use maxlength to limit the number of characters input into a
text field. Example: maxlength=12. When the fieldflags is set to comb, the value of
maxlength determines the number of combs in the field.
\TU tooltip=string
Command Description: Enter a text value to appear as a tool tip. A tool tip is text that
appears in a frame when the user hovers the mouse over the field. The link annota-
tion does not have a tool tip feature. Enclose in parentheses if the text string con-
tains a comma; for example, tooltip={Hi, press me and see what happens!}.
The tooltip key obeys the unicode option. If the unicode option of hyperref is in
effect, then setting
tooltip = {J\"{u}rgen, press me and see what happens!}
yields a tool tip of “Jürgen, press me and see what happens!”
\DV default=string
\V value=string
Command Description: Set default value of a field (text, list, combobox) using the
default key. The default value is the value used for the field when the field is reset.
Example: default=Name.
The value key is used to set the current value of a field (text, list, combobox).
Example: value=AcroTeX.
These two keys obey the unicode option. If the unicode option of hyperref is in
effect, then setting value = \texteuro\ 1 000 000 sets the (initial) value of this
field to “€ 1 000 000”.
\R rotate=0|90|180|270
Command Description: Set the orientation of the field, values are 0, 90, 180 and 270.
If 90 or 270 are chosen, the height and width of the field need to be reversed. This is
not done automatically by eforms
\BG bgcolor=numnumnum
Command Description: The background color of a form field. This is a RGB color value.
\CA uptxt=string
\AC downtxt=string
\RC rollovertxt=string
Command Description: The normal (mouse up), mouse down and rollover text for a
button field. All three of these keys obey the unicode option. If the unicode option
of hyperref is in effect, then setting uptxt = J\"{u}rgen yields a normal caption of
“Jürgen” on the button.
Pushbuttons only. The following list of keys are used for creating custom appearances
b on button faces. Acrobat Distiller required for this set. The example files eqforms.pdf
and eqforms_pro.pdf illustrate the creation of icons as button appearances. In the
latter PDF, eqforms_pro.pdf, Acrobat Distiller is required to be the PDF creator.
\I normappr=string
\RI rollappr=string
\IX downappr=string
\importIcons importicons=yes|no
Command Description: The normal, rollover, and down appearances of the but-
ton face icon. The value of each key is an indirect reference to a form XObject.
Normally, you can use the graphicxsp package to embed graphics and give a
symbolic name which is used as the value of these keys. importIcons is a special
key used in conjunction with importing icons using JavaScript methods.
\TP layout=labelonly|icononly|icontop|iconbottom|
iconleft|iconright|labelover
Command Description: The value of this key determines the layout of the icon
relative to the label (or caption). The default is labelonly, if if you define icons,
you need to set layout to something other than labelonly.
\SW scalewhen=always|never|iconbig|iconsmall
Command Description: The value of this key tells when to scale the icon. The
iconbig scales the icon when it is too big for the bounding rectangle; while
iconsmsll scales the icon when it is too small for the bounding rectangle. The
default is always.
\ST scale=proportional|nonproportional
Command Description: This parameter sets the scale type, either proportional
scaling, where the aspect ratio of the icon is preserved; or nonproportional
scaling is used. The default is proportional.
\PA position=xy
Command Description: Both x and y are numbers between 0 and 1, inclusive,
and separated by a space (not a comma). They indicate the fraction of the left
over space to allocate at the left and bottom of the icon. A value of {0.0 0.0}
positions the icon at the bottom-left corner; a value of {0.5 0.5} centers it within
the rectangle. This entry is only used of the icon is scaled proportionally. The
default is {0.5 0.5}.
\FB fitbounds=true|false
Command Description: A Boolean value, if true, indicates that the button ap-
pearance should be scaled to fit fully within the bounds of the field’s bounding
rectangle without taking into consideration the line width of the border. The
default is false. fitbounds is the same as fitbounds=true.
Check boxes and Radio Buttons Only. The following list of keys are used for creating
custom appearances on check boxes and radio buttons. Acrobat Distiller required for
b this set. The example files eqforms.pdf and eqforms_pro.pdf illustrate the creation
of these appearances. In the latter PDF, eqforms_pro.pdf, Acrobat Distiller is required
to be the PDF creator.
\AP appr={ norm={on={normOnAppr},off={normOffAppr}},

down={on={downOnAppr},off={downOffAppr}},
roll={on={rollOnAppr},off={rollOffAppr}}}
Command Description: The norm key is the normal appearance of the button;
it has two appearances, the on and the off appearances. The on and off are
indirect references to a form XObject. The other two keys, down and roll, are
the down and rollover appearances, respectively; they have the same structure as
norm does.
If appr is not specified, then, by default, the usual appearances of the buttons are
used, as provided by Acrobat/AR.
The down and roll are optional, if you use appr at all, you should specify the
norm appearance, both on and off appearances.
\Q align=left|centered|right
Command Description: The type of alignment of a text field. Permitted values are
left, centered, and right.
\textFont textfont=font_name
\textSize textsize=num
\textColor textcolor=num[numnum[num]]
Command Description: The key textfont is the text font to be used with the text of
the field, while textsize is the text size to be used. A value of 0 means auto size. The
color of the text in the field. This can be in G, RGB or CMYK color space by specifying
1, 3 or 4 numbers between 0 and 1.
\autoCenter autocenter=yes|no
Command Description: This is a feature of eforms. Use autocenter=yes (the default)

to moderately center the bounding box, and use autocenter=no otherwise.
\inline inline=yes|no
Command Description: Same as \autoCenter (autocenter), but the algorithm for

positioning the field is more sophisticated. The default is autocenter=no
To compare the last two (autocenter and inline), we present the following exam-
ple:
Enter your name: D. P. Story (inline=yes)
Enter your name: D. P. Story (autoCenter=yes)
\presets presets=\CMD
Command Description: Set presets from inside a \ui argument. The value of \ui must
be a user defined command, which expands to a comma-delimited list of ui-key-value
pairs.
Example 13. Use the presets key to place pre-defined key-value pairs into the option
argument of a link. Define a command,
\def\myUIOpts{%
border=visible,linktxtcolor=blue,
linewidth=medium,highlight=outline,
linestyle=dashed,bordercolor={1 0 0},
js={app.alert("AcroTeX rocks!")}
}
Later, we can type,
\setLink[\ui{presets={\myUIOpts}}]{Press Me Again!!}
\symbolchoice symbolchoice=check|circle|cross|diamond|square|star
Command Description: Used with a checkbox or radio button field. This sets the
symbol that appears in the field when the box is checked. Choices are check, circle,
cross, diamond, square, and star.
6.2. The Action Tab

There are several common actions that are supported through the user-friendly inter-
face, these are goto actions, and JavaScript actions.
goto={KV-pairs}
Command Description: This key incorporates jumps to pages and destinations within
the current PDF file, and to pages and destinations to another PDF file. these are
Key-Value Pairs: There are a number of key-value pairs that are recognized, file,
targetdest, labeldest, page, view, and open. A brief description of each follows.
1. file: Specify a relative path to the PDF file. This will work on the Web if the
position is the same relative to the calling file. If the file key is not present, the
jump is to a page or destination in the current file.
2. url: This key is used to create a weblink, similar to what \href does. The value
of this key is a url (http, https, mailto, etc.). If the url key is present, only the
openparams key is recognized.
3. openparams: Open parameters that should be included with the URL, as passed by
the url key. These parameters are key value pairs key=value and are separated
by an ampersand (&). See Parameters for Opening PDF Files for more information,
examples are found below.
4. targetdest: Jump to a target, perhaps created by \hypertarget. For example,

if we say \hypertarget{acrotex}{Welcome!}, we jump to the acrotex named
destination by specifying targetdest=acrotex.
5. labeldest: Same as targetdest, but we jump to a destination specified by a

latex label. For example, if we type \section{AcroTeX}\label{acrotex}, we
can jump to this section by specifying labeldest=acrotex.
6. page: The page number to which the goto action is to jump. If we set page=1, we
will jump to the first page of the document.
7. view: The view can be set when the page key is used. Possible values are fitpage,
actualsize, fitwidth, fitvisible, and inheritzoom. These terms correspond
to Acrobat’s UI. When jumping to a destination, the view is set by the destination
code.
8. open: This key is used when you specify the file key. The open key determines
if a new window is opened or not when the PDF viewer jumps to the file. Possible
values are userpref (use user preferences), new (open new window), existing
(use the existing window).
Example 14. The following are examples of the goto key.
• AeB Manual
\setLink[\ui{goto={file=aeb_man.pdf,page=8,%
view=fitwidth}}]{AeB Manual}
This link should work on your local hard drive and it should work on the web,
from within a web browser, assuming aeb_man.pdf is in the same folder as
eformman.pdf.
• AeB Manual on Web
\setLink[\ui{%
goto={url=http://www.math.uakron.edu/˜dpstory/%
acrotex/aeb_man.pdf,%
openparams={page=8&search=AcroTeX web exerquiz}}}
]{AeB Manual on Web}
Here, we open the AeB Manual that is on the web, go to page 8, and search for
the words AcroTeX, web, and exerquiz. Notice that we don’t have to do anything
special with the tilde (˜) or the sharp (#), both of these are handled by the eforms
package.
\A{\JS{script}} js={script}
Command Description: A general purpose key to execute JavaScript actions on a mouse

up trigger. The argument is a JavaScript text string, for example,
js={app.alert("Hello World!")}
The value of js may be a macro containing JavaScript, which would include a macro
created by the defineJS environment of insdljs.
mouseup={script}
mousedown={script}
onenter={script}
onexit={script}
onfocus={script}
onblur={script}
format={script}
keystroke={script}
validate={script}
calculate={script}
pageopen={script}
pageclose={script}
pagevisible={script}
pageinvisible={script}
Command Description: These are all additional actions (AA) of a form field, which take
as their values JavaScript code (script).
• mouseup: Executes its code with a mouse up event. If there is a JavaScript action
defined by the js key (or the \A key), the js (\A) action is executed.
• mousedown: Executes its when the mouse is hovering over the field and the user
clicks on the mouse.
• onenter: Executes its code when the user moves the mouse into the form field
(the bounding rectangle).
• onexit: Executes its code when the user moves the mouse out of the form field
(the bounding rectangle).
• onfocus: Executes its code when the user brings the field into focus.
• onblur: Executes its code when the user brings the field loses focus (the user tabs
away from the field, or click outside the field).
• format: JavaScript to format the text that appears to the user in a text field or
editable combo box.
• keystroke: JavaScript to process each keystroke in a text field or editable combo

box.
• validate: JavaScript to validate the committed data input into a text field or
editable combo box.
• calculate: JavaScript to make calculations based on the values of other fields.
• pageopen: JavaScript that executes when the page containing the field is opened.
• pageclose: JavaScript that executes when the page containing the field is closed.
• pagevisible: JavaScript that executes when the page containing the field first
becomes visible to the user.
• pageinvisible: JavaScript that executes when the page containing the field is
no longer visible to the user.
6.3. The Signed Tab

A signature field has a Signed tab. On that tab is an option to mark a set of fields as
readonly (locked). The locked key controls that option.
\Lock lock={PDF KV-pairs}

Command Description: The lock key is used with signature fields, currently, there is
no nice user interface to this key. Typical entries are
lock={/Action/All} % lock all fields in the doc

lock={/Action/Include % lock all fields listed in Fields
/Fields [(field1)(field2)...]}
lock={/Action/Exclude % lock all fields not listed in Fields
/Fields [(field1)(field2)...]}
Another option that is included in the Signed tab is titled “This script executes when
field is signed.”
This is an option that, through the user interface, is mutually exclusive from locking
fields. This option is implemented through the format event; thus, to populate this
option with JavaScript use the format key. For example,
format={app.alert("Thank you for signing this field.");}

41
Setting the Tab Order

The taborder package is an internal AeB package that is called by both the eforms and
the annot_pro packages. The taborder package sets the tab order for form fields
and link annotations (when the link is created by the command \setLink, defined in the
eforms package. The package works for all drivers when setting tab order by column,
row, or widget order. For setting tabbing order by structure, only documents generated
using the pdfmark are supported; those using the dvips or dvipsone driver along with
Adobe Distiller.
7. Setting the Tab Order

The tabbing order of the fields is usually the order in which the fields were created. In
rare cases, it may be desirable to set the order to one of the orders defined by the PDF
Reference.
\setTabOrder{c|C|r|R|s|S|w|W|a|A|unspecified}
Command Description: Command Description: This command is page oriented, it sets

to the tab order of fields on the page the TEX compiler executes this command. The
permissible values of the parameter are described below, taken verbatim from the PDF
Reference, the cross-references that appear in the descriptions are references to the
PDF Reference document.
• c|C (column order): “Annotations are visited in columns running vertically up

and down the page. Columns are ordered by the Direction entry in the viewer
preferences dictionary (see Section 8.1, ‘Viewer Preferences’). The first annotation
visited is the one at the top of the first column. When the end of a column is
encountered, the first annotation in the next column is visited.”
• r|R (row order): “Annotations are visited in rows running horizontally across
the page. The direction within a row is determined by the Direction entry in the
viewer preferences dictionary (see Section 8.1, ‘Viewer Preferences’). The first
annotation visited is the first annotation in the topmost row. When the end of a
row is encountered, the first annotation in the next row is visited.”
• s|S (structure order): “Annotations are visited in the order in which they appear in
the structure tree (see Section 10.6, “Logical Structure”). The order for annotations
that are not included in the structure tree is application-dependent.”
• w|W (version 9.0, widget order): “Widget annotations are visited in the order in
which they appear in the page Annots array, followed by other annotation types
in row order.”
• a|A (version 9.0, annotations array order): “All annotations are visited in the order
in which they appear in the page Annots array.” (In version 9.0, this key is not
implemented.)
• unspecified|empty The tab order follows the order of the annotations as listed
in the Annots array. For LATEX, this is the order in which the annotations were
created. You get the same result if the argument is left empty \setTabOrder{},
or if \setTabOrder is not used at all. If an unrecognized argument is passed to
\setTabOrder, unspecified is used.
The behavior of tabbing has changed over the years; documentation of tabbing behavior
is given in the Adobe Supplement to the ISO 32000, BaseVersion 1.7, ExtensionLevel 3.6
See the section Errors and Implementation Notes. Annotations include things like form
fields (widget annotations), links (link annotations) and the various types of comment
annotations. See section 8.4.5 of the PDF Reference.
The \setTabOrder command is available for users of pdftex and dvipdfm, as well
as users of dvipsone and dvips (with distiller); for row, column, and widget (version
9 or later), the PDF viewer does all the work on tabbing, for tabbing using structure,
one necessarily needs structure, otherwise, the tabbing follows row order. For users
of Adobe Distiller, the taborder package provides two ways for defining the structure
order; on any page in which structure order is used, use only one of the following
commands:
\setTabOrderByList
\setTabOrderByNumber
7.1. Using \setTabOrderByList

We illustrate with a simple example, followed by a verbatim listing of the code, and a
discussion afterward. We begin by placing two text fields in a row; normally,we would
tab from the first one created by the TEX compiler to the next one created. We use
structure to reverse the order of tabbing.
text1
text2
The verbatim listing of the above form fields follows:
\setTabOrder{s} % set tab order to structure

\setTabOrderByList % the default initially
\textField[\V{text1}\objdef{otext1}]{text1}{1.25in}{11bp}\\[3bp]
\textField[\V{text2}\objdef{otext2}]{text2}{1.25in}{11bp}
\setStructTabOrder{% The list of the fields in the desired order

{otext2}
{otext1}
}
We begin by specifying \setTabOrder{s} structure tab order. In the optional argument

of the two text fields, we specify an object name for each. These names must be unique
6 http://www.adobe.com/devnet/acrobat/pdfs/PDF3200_2008.pdf
throughout the whole document; they are used to reference the fields when setting up
the tabbing order.
The \setStructTabOrder is used to set up the tabbing order, its arguments (en-
closed in braces) consists of a list of object names (which must exist on the current
page). The order of the object names is the order of visitation when you tab. PDF
objects not referenced are visited last after the structure tabbing is complete.
After all annotations have been created on a page, we use the \setStructTabOrder
to actually set the tab order; this is none by simply listing the object names, in the
desired order, of the annotations you want included in the tabbing order. These anno-
tations can be fields, links, and markup comments, like sticky notes.
The syntax for \setStructTabOrder is
\setStructTabOrder{%
[type=type,title=title]{oRef_1}
[type=type,title=title]{oRef_1}
...
[type=type,title=title]{oRef_n}
}
Each argument has an optional argument, the required argument (<oRef_i>) is an

object name of a previously defined PDF object, such as a form field (widget), a link, or
an annotation. The optional argument takes two optional key-value pairs: (1) The type
is a declaration of the type the PDF object is, the default is Form (you can use Link if
its a link, and Annot if its a comment); (2) title is the title of the structure, the value
of title appears in the Tags panel of the Acrobat user interface. The default title is to
have no title.
b The demo file is settaborder.pdf for these tabbing features, including tabbing using
structure, has its source file attached to the PDF file. The file is posted one the AeB Blog.
7.2. Using \setTabOrderByNumber

An alternate method for setting tab order by structure is to directly enter the tab order
into the optional argument of the field, link, or comment annotation.
text3
text3
The verbatim listing of the above form fields follows:
\setTabOrder{s} % set tab order to structure

\setTabOrderByNumber
\textField[\V{text3}\objdef{otext3}\taborder{1}]
{text3}{1.25in}{11bp}\\[3bp]
\textField[\V{text3}\objdef{otext4}\taborder{0}]
{text4}{1.25in}{11bp}
Note the user of the \objdef and \taborder keys. The latter is used to set the order
of tabbing.
Important: When setting tab order, there must be an object with \taborder{0}; from
what I’ve been able to observe, if no PDF object has tab order zero, the tabbing reverts
to what is listed in the Annots array, which is the order the PDF objects were created.
If you specify 0, 0, 1, 2, 3…, then the two PDF objects with tab order of 0 are visited in
the order they were created. Similarly, for the other tab values. A tab order of 0, 2, 3,
4…seems to work as well. The object labeled 2 will be visited after the object labeled
0.
b The demo file is settaborder1.pdf for these tabbing features, including tabbing using
structure, has its source file attached to the PDF file. The file is posted one the AeB Blog.
45
Document and Page JavaScript

The insdljsPkg package provides support to LATEX in four areas:
1. for embedding document level JavaScript into the PDF file created from a LATEX
source, the insDLJS environment.
2. for creating open page actions that are executed when the document is first
opened to the first page, the \OpenAction command.
3. for writing JavaScript code in an environment that preserves the formatting of the
code, this is the defineJS environment.
4. for executing JavaScript code once to perform post-distillation tasks, this is the
execJS environment. This environment works only for document authors that
use Acrobat/Acrobat Distiller to create PDF files.
This package defines a new environment, insDLJS, used for inserting Acrobat Java-
Script into a PDF file created from a LATEX source. This package works correctly for
Acrobat users of pdftex (and luatex), dvipdfm, dvipdfmx, and xetex. For those who use either
required for dvips or dvipsone to produce a postscript file, which is then distilled, you are required
dvips to have Acrobat 5.0 (or later).
8. Package Options
The insdljs supports five common “drivers”: dvipsone, dvips, pdftex (including the
executable lu(la)tex), dvipdfm, dvipdfmx, xetex, and textures. When using dvipsone
or dvips, Acrobat Distiller and Acrobat (version 5.0 or later) are required to embed the
JavaScripts at the document level. The other drivers have primitives that allow the
embedding of the JavaScripts.
Other options are discussed in the following paragraphs.
nodljs turns off the embedding of the document level JavaScript. This might be useful,
for creating a paper document that is not interactive. For a non-interactive paper
document, no JS is needed.
execJS is a very useful option/feature if you know how to use it. Any JavaScript that
is written in an execJS environment is executed once when the document is first
opened in Acrobat, then discarded. AeB uses this for post-distillation document
processing. The default is that the JavaScript in an execJS environment is not
executed; using this option turns on this feature.
9. The insDLJS and insDLJS* Environments

These are the main environments defined by this package. There are two forms of the
document level environment, the insDLJS and the insDLJS*. First, we discuss what a
document JavaScript is.
The insDLJS and insDLJS* Environments 46
9.1. What is Document Level JavaScript?

The document level is a location in the PDF document where scripts can be stored.
When the PDF document is opened, the document level functions are scanned, and any
“exposed script” is executed.
Normally, the type of scripts you would place at the document level are general pur-
pose JavaScript functions, functions that are called repeatedly or large special purpose
functions. Functions at the document level are known throughout the document, so
they can be called by links, form buttons, page open actions, etc.
Variables declared within a JavaScript function have local scope, they are not known
outside that function. However, if you can declare variables and initialize them at the
document level outside of a function, these variables will have document wide scope.
Throughout the document, the values of these global variables are known. For example,
suppose the following code is at the document level:
var myVar = 17; // defined outside a function, global scope

function HelloWorld()
{
var x = 3; // defined inside a function, local scope
app.alert("AcroTeX, by Hech!", 3);
}
Both the function HelloWorld() and the variable myVar are known throughout the
document. The function HelloWorld() can be called by a mouse up button action;
some form field, executing some JavaScript, may access the value of myVar and/or
change its value. The variable x is not known outside of the HelloWorld() function.
9.2. The insDLJS Environment

The insDLJS is the simplest of the two environments. Any material within the envi-
ronment, eventually ends up in the DLJS section of the PDF document.
The environment takes the base_name and writes the file base_name.djs. This
file contains a verbatim listing of the JavaScript within the environment, plus some lines
that change catcodes. The file is then input into the document at \AtBeginDocument.
The case of dvipsone and dvips is a little different. A base_name.djs is written
and input back, and a second file base_name.fdf is written. The second file is later
input into the PDF document after distillation.
The syntax of usage for this environment, which takes three arguments, is given
next.
\begin{insDLJS}[js_var]{base_name}{script_name}
...
JavaScript functions or exposed code
...
\end{insDLJS}
Environment Description: JavaScript code is written within the insDLJS environment.

The code is stored as document-level JavaScript, and is global to the document. Func-
tions and variables defined at the top-most level are known to other form elements in
the document.
The insDLJS is a verbatim environment, with backslash (\) and percentage (%) main-
taining their usual LATEX meaning. Commands defined in the LATEX source file, therefore,
are expanded before the JavaScript is embedded in the PDF file. The left and right
braces are set to normal characters, so the commands can’t have any argument, they
should be just text macros.
Parameter Description: The environment takes three parameters, the first is optional,
but required when using the Acrobat Distiller.
[js_var] is an optional parameter was required for the dvipsone and dvips options;
otherwise it is ignored. Its value must be the name of one of the functions or
JavaScript variables defined in the environment. This is used to detect whether
the DLJS has already been loaded by Acrobat.
☛ The [js_var] is now optional even for users of dvipsone and dvips. If one is not
provided, then appropriate code is automatically generated.
base_name is an alphabetic word with no spaces and limited to eight characters.7 It is

used to build the names of auxiliary files and to build the names of macros used
by the environment.
script_name is the name of the JavaScript that you are embedding in the document.
This title will appear in the document JavaScript dialog in Acrobat; unless you use
Acrobat, you can’t see this name in the user interface anyway. The script_name
should be a string that is descriptive of the functionality of the code.
Commenting. Within the insDLJS environment, there are two types of comment char-
acters: (1) a TEX comment (%) and (2) a JavaScript comment. The JavaScript comments
are ‘//’, a line comment, and ‘/*...*/’ for more extensive commenting. These com-
ments will survive and be placed into the PDF file. In JavaScript the ‘%’ is used as well, use
\% when you want to use the percent character in a JavaScript statement, for example
app.alert("\%.2f", 3.14159);, this statement will appear within your JavaScript
code as app.alert("%.2f", 3.14159);.
Example 15. The following is a minimal illustration of the use of the new environment.
Here we assume the document author is using pdftex, and is not using the wonderful
packages of web, exerquiz or eforms. In this case, the hyperref package with driver in
the option must be introduced first, followed by insdljs with the same driver, of course.
The optional argument of the insDLJS environment is not used in this example.
\usepackage[pdftex]{hyperref}
\usepackage[pdftex]{insdljs}
7 There is actually no limitation on the number of characters in the name, this is a legacy statement from
the days of DOS, you remember DOS, don’t you?

\newcommand\tugHello{Welcome to TUG 2001!}

\begin{insDLJS}{mydljs}{My Private DLJS}
function HelloWorld() { app.alert("\tugHello", 3); }
\end{insDLJS}
\begin{document}
\begin{Form} % a hyperref environment, needed for \PushButton
% use built in form button of hyperref
Push \PushButton[name=myButton,onclick={HelloWorld();}]{Button}
\end{Form}
\end{document}
The Form environment and the \PushButton command are defined in the hyperref
package. The insDLJS uses the Form environment, the eforms package defines its own
\pushButton command.
Example 16. Here is the same example as above, but with dvips as the driver and us-
ing the eforms package, which calls insdljs. Note the use of the optional argument
in the insDLJS environment, and the missing hyperref package statement and Form
environment, the eforms package automatically inserts this code.
\usepackage[dvips]{eforms}
\newcommand\tugHello{Welcome to TUG 2001!}

\begin{insDLJS}[HelloWorld]{mydljs}{My Private DLJS}
function HelloWorld() { app.alert("\tugHello", 3); }
\end{insDLJS}
\begin{document}
\pushButton[\CA{Push}\A{\JS{HelloWorld();}}]{Button}{}{11bp}
\end{document}
9.3. The insDLJS* Environment

The insDLJS* environment can be used to better organize, edit and debug your Java-
Script. It is suitable for package developers who write a large amount of code package
application.
If you have the full Acrobat product, you can open the DLJS edit dialog. There you
will see a listing of all DLJS contained in the document. When you double click on
one of the script names, you enter the edit window, where you can edit all JavaScript
contained under that name.
\begin{insDLJS*}[js_var]{base_name}
\begin{newsegment}{script_name_1}
\end{newsegment}
\begin{newsegment}{script_name_2}
\end{newsegment}
...
...
\begin{newsegment}{script_name_n}
\end{newsegment}
\end{insDLJS*}
Parameter Description: The environment takes two parameters, the first is optional,
but required when using the Acrobat Distiller. The nested environment newsegment
takes one required parameter.
[js_var] is an optional parameter, its use is discouraged.
base_name is an alphabetic word with no spaces and limited to eight characters. It is

used to build the names of auxiliary files and to build the names of macros used
by the environment.
script_name_i is the script name (title) that appears in the Document level JavaScript
dialog of Acrobat.
9.4. Escaping
JavaScript uses the backslash as an escape character, just as does TEX. The insdljs
pacakge tries to make the transition from TEX to JavaScript as easy as possible. In the
table below, is a listing of the more useful characters represented by a backslash.
Sequence Character represented
\t horizontal tab (\u0009)
\n newline (\u000A)
\r carriage return (\u000D)
\" double quote (\u0022)
\’ apostrophe or single quote (\u0027)
\\ backslash (\u005C)
\xXX the Latin-1 character specified by the two hexadecimal digits XX
\uXXXX the unicode character specified by the four hexadecimal digits XXXX
\XXX the Latin-1 character specified by the octal digits XXX, between
1 and 377.
Within a JavaScript string, these special characters should be double escaped, \\, like
so:
Push Me
\pushButton[\textFont{Arial}\CA{Push Me}\A{\JS{%
app.alert("The \\"cost\\" of this package is \\u20AC 0.\\rThis,
\\"\\\\\\" is a backslash");
}}]{demoEsc}{}{11bp}
Note the double backslash of backslash, which comes out to four, count them four
backslashes, ‘’\\\\”.
Again, both JavaScript and TEX, certain punctuation marks have special meaning; in
the case of JavaScript, punctuation has a special meaning within regular expressions:
Special Punctuation in Regular Expressions
ˆ $ . * + ? = ! : | \ / ( ) [ ] { }
When these occur in a regular expression, within a string, they need to be double es-
caped, \\. Outside of a sting, they need only be escaped.
Example 17. The following code searches through the string str and replaces every
occurrence of the period character with “\.”.
str = "AcroTeX rocks. AcroTeX rolls."
str = str.replace(/\./g, "\\.");
When this code is executed, the result is “AcroTeX rocks\. AcroTeX rolls\.”.
Example 18. If one of these special characters appears outside a JavaScript string,
within a regular expression pattern, for example, they need only be escaped. The code
(/\)\ˆ\(/.test(str)) searches the string str for any occurrence of “)ˆ(” and re-
turns true if such a pattern is found, false otherwise. If str="(x+1)ˆ(3)", the search
returns true.
9.5. Access and Debugging

For those who do not have Acrobat, the application, unless you are writing very simple
code, writing and debugging JavaScript will be very difficult. From the Acrobat Reader,
there is no access to the document JavaScript. You will be pretty much writing blind.
Normally, I develop the JavaScript from within Acrobat. The GUI editor does check
for syntax errors, giving you a chance to correct some simple errors as you go. After
I am satisfied with my code, I copy it from the editor and paste it into a insDLJS
environment. This is how the JavaScript code of exerquiz was developed.
In my opinion, if you want to develop rather complicated code, having the full Ac-
robat product is a must. (This implies that the Windows or Mac platform is needed!)
9.6. JavaScript References

The JavaScript used by Acrobat consists of the core JavaScript plus Acrobat’s Java-
Script extensions. The Core JavaScript Reference [2] may be found at Mozilla De-
veloper Center. The documentation for the Acrobat extensions may be found in the
guides JavaScript for Acrobat API Reference [4] and Developing Acrobat Applications
using JavaScript [3], both of which I’ve had a hand in writing. These are found at
Acrobat Developer Center. (Click on JavaScript for Acrobat in the right-hand naviga-
tion panel.)
51
10. Open Action

This package also defines an \OpenAction command to introduce actions that are
executed when the PDF document is opened on page 1. The open action command only
applies to page 1.
\OpenAction{action_code}
Command Location: This command must appear in the preamble of the document.
Command Description: Executes the action(s) each time page 1 is opened. The ar-
gument <action_code> is any action subtype, as listed in Section 8.5.3 of the PDF
Reference, sixth edition, PDF 1.7. Two common types are JavaScript and Named actions.
The \OpenAction command may be repeated, which will add to the list of open actions
to be executed at the opening of page 1.
Special commands are defined in insdljs, \JS and \Named, that make it easy to spec-
ify these types of actions.
Example 19. \OpenAction{\JS{app.alert("Hello World!");}}
Example 20. You can use \r and \t—carriage return and tab, respectively—to format
multiple lines of JavaScript:
\OpenAction{\JS{%
app.alert("Hello World!");\r
app.alert("Good Day to You!");
}}
Example 21. Multiple \OpenAction can be entered. Code is executed in the same order.
Here, we show an alert box with a message, then jump to the last page.
\OpenAction{\JS{app.alert("AcroTeX rocks the world!");}}

\OpenAction{\Named{LastPage}}
For the other pages, beyond page 1, \thisPageAction can be used; the command can
also be used for page 1 as well (it must go in the preamble).
\thisPageAction{open_script}{close_script}
Command Location: For page 1, this command must go in the preamble, otherwise, it
goes on the page for which it is intended.
Command Description: open_script is an action that is to be executed when the
current page is opened; close_script is an action to be executed when the current
page is closed.
Example 22. Below is a simple example of how to use \thisPageAction.
...
\thisPageAction{\JS{console.println("Open: page 1");}}
{\JS{console.println("Close: page 1");}}
52
\begin{document}
page 1
\newpage
page 2
\thisPageAction{\JS{console.println("Open: page 2");}}
{\JS{console.println("Close: page 2");}}
...
\end{document}
When \thisPageAction is executed in the preamble, the <open_action> argument

gets passed to the \OpenAction command.
11. The execJS Environment

This is an environment useful to PDF developers who want to tap into the power of
JavaScript. To use this environment, the developer needs Acrobat 5.0 or higher. pdftex
or dvipdfm can be used to produce the PDF document, but the developer needs the
Acrobat product for this environment to do anything.
The execJS is used primarily for post-distillation processing (post-creation pro-
cessing, in the case of pdftex and dvipdfm). The execJS environment can be used, for
example, to automatically import named icons into the document, which can, in turn,
be used for an animation.
The execJS is an environment in which you can write verbatim JavaScript code. This
environment is a variation on insdljs, it writes a couple of auxiliary files to disk; in
particular, the environment creates an .fdf file. When the newly produced PDF is
loaded for the first time into the viewer (Acrobat, not Reader), the .fdf file generated
by the execJS environment is imported, and the JavaScript executed. This JavaScript is
not saved with the document. The syntax of this environment is…
\begin{execJS}{name}
....
JavaScript code
....
\end{execJS}
Parameter Description: The environment takes one required argument, the base name
of the auxiliary files to be generated.
Many of the more useful JavaScript methods have security restrictions, the developer
must create folder JavaScript that can be used to raise the privilege of the methods.
Example 23. Here is an extensive example taken from the AeB Pro distribution. The
following code is user folder JavaScript code, see the AeB Pro documentation on how
to locate the user JavaScript folder. We define a function aebTrustedFunctions that
is the interface to accessing the restricted methods.
/*
AEB Pro Document Assembly Methods
53
Copyright (C) 2006 AcroTeX.Net

D. P. Story
http://www.acrotex.net
Version 1.0
*/
if ( typeof aebTrustedFunctions == "undefined") {
aebTrustedFunctions = app.trustedFunction(
function ( doc, oFunction, oArgs ) {
app.beginPriv();
var retn = oFunction( oArgs, doc )
app.endPriv();
return retn;
});
}
// Add a watermark background to a document
aebAddWatermarkFromFile = app.trustPropagatorFunction (
function ( oArgs, doc ) {
app.beginPriv();
return retn = doc.addWatermarkFromFile(oArgs);
app.endPriv();
});
Once this code is installed in the user JavaScript folder, and Acrobat is re-started,
the code is ready to be used. The way the code is used is with the execJS environment.
\def\bgPath{"/C/acrotex/ManualBGs/Manual_AeB.pdf"}
\begin{execJS}{execjs}
aebTrustedFunctions( this, aebAddWatermarkFromFile,
{bOnTop: false, cDIPath: \bgPath} )
\end{execJS}
This is the code used to prepare this manual. It places a background graphic on each
page of the document. When the newly distilled document is first opened in Acrobat,
(version 7.0 or higher, is when the privilege bit started to appear), the trusted function
aebTrustedFunctions is executed with its arguments. Looking at the definition of
aebTrustedFunctions, what is executed is
app.beginPriv();
return retn = this.addWatermarkFromFile({bOnTop: false,
cDIPath: "/C/acrotex/ManualBGs/Manual_AeB.pdf"});
app.endPriv();
AeB Pro, the AcroTEX Presentation Bundle and @EASE use these execJS techniques.
12. The defineJS Environment

When you create a form element (button, text field, etc.), you sometimes want to attach
JavaScript. The defineJS environment aids you in writing your field level JavaScript. It
The defineJS Environment 54
too is a verbatim environment, however, this environment does not write to an auxiliary
file, but saves the contents in a token register. The contents of the register are used in
defining a macro that expands to the verbatim listing.
\begin{defineJS}[chngCats]{\cmd}
script
\end{defineJS}
Parameter Description: The defineJS environment takes two parameters, the first
optional. the required parameter is the command name to be defined. Use the op-
tional first parameter (chngCats) to modify the verbatim environment, as illustrated
in the example below. The script is saved under the command name \cmd. The
defineJS is a complete verbatim environment: no escape, and no comment characters
are defined. You can use the optional parameter to create an escape character; you can
pretty much use any character you wish, except the usual one ‘\’, backslash.
Example 24. The following example illustrates the usage of the defineJS environment.
% Make @ the escape so we can

% demonstrate the optional parameter.
\def\HelloWorld{Hello World!}
\begin{defineJS}[\catcode‘\@=0\relax]{\JSA}
var sum = 0;
for (var i = 0; i < 10; i++)
{
sum += i;
console.println("@HelloWorld i = " + i );
}
console.println("sum = "+sum);
\end{defineJS}
\begin{defineJS}{\JSAAE}
console.println("Enter the button area");
\end{defineJS}
\begin{defineJS}{\JSAAX}
console.println("Exiting the button area");
\end{defineJS}
\pushButton[\A {\JS{\JSA}}
\AA{\AAMouseEnter{\JS{\JSAAE}}
\AAMouseExit{\JS{\JSAAX}}}
]{myButton}{30bp}{15bp}
The code lines of \JSAAE and \JSAAX are so simple, defineJS environment was really
not needed.
See ‘Inserting Complex or Lengthy JavaScript’ on page 28 for an additional example of
the use of the defineJS environment.
The insdljs package defines two “silent” versions of defineJS, @defineJS and
defineJS*.
\begin{@defineJS}[chngCats]{\cmd}
script
\end{@defineJS}
defineJS* is a public version @defineJS
\begin{defineJS*}[chngCats]{\cmd}
script
\end{defineJS*}
Use defineJS* in the body of the document; the command argument \cmd can be
silently used and redefined in a later defineJS* environment. The @defineJS envi-
ronment is for package authors.
The defineJS-type environments with arguments. The defineJS-type environments
do not have parameters/arguments as normal environments (or commands) do. To
enable the ability to modify the JavaScript code within the environment of defineJS,
the command pair \bParams/\eParams is defined.
\bParams{token1 }{token2 }...{tokenn }\eParams
When you use one of the defineJS environments to define field level JavaScript, you
can include symbolic parameters/arguments \p(1), \p(2), and so on, within the body
of the environment. At the time of expansion of the command \cmd, a substitution
is made: \p(1) expands to token1 , \p(2) expands to token1 , and so on. Note that
the argument of \p, which is only locally defined, is enclosed with parentheses. Before
continuing with the discussion, consider the following example.
\begin{defineJS*}[\catcode‘\!=0\relax]{\myCode}
var p1=!p(1), p2=!p(2);
app.alert("p1 + p2 = " + Number(p1+p2) );
\end{defineJS*}
Within the body of a defineJS environment, there is no escape character unless you
change catcode of another character within the optional argument of the defineJS
environment. In the above example, the exclamation mark is declared as the escape.
\pushButton[\cmd{\bParams{1}{16}\eParams}
\A{\JS{\myCode}}]{pbfld1}{.5in}{11bp}
When this button is pressed, an alert message appears ‘p1 + p2 = 17’. We can reuse
this code later with other parameters:
\pushButton[\cmd{\bParams{77}{11}\eParams}
\A{\JS{\myCode}}]{pbfld2}{.5in}{11bp}
Now the message is ‘p1 + p2 = 88’.

In both examples, the special key \cmd is used to pass the \bParams/\eParams com-
mand pair into eforms’ parsing stream; this keeps the declaration local. The \cmd key
is described in Appendix C, titled ‘Supported Key Variables’, beginning on 59; specifi-
cally, \cmd is listed in under the heading Specialized, non-PDF Spec commands.
57
Appendices
A. The Annotation Flag F
The annotation flag F is a bit field that is common to all annotations.
Annotation Flag F
Flag Description
\FHidden hidden field
\FPrint print
\FNoView no view
\FLock locked field (PDF 1.4)
In the user interface for Acrobat, there are four visibility attributes for a form field. The
table below is a list of these, and an indication of how each visibility attribute can be
attained through the F.
UI Description Use
Visible (and printable)
Hidden but printable \F{\FNoView}
Visible but doesn’t print \F{\FNoPrint}
Hidden (and does not print) \F{\FHidden}
All fields created by the eForm commands are printable by default.

58
B. Annotation Field flags Ff

The table below lists some convenience macros for setting the Ff bit field.
Annotation Field flags Ff

Flag Description Fields
\FfReadOnly Read only field all
\FfRequired Required field (Submit) all
\FfNoExport Used with Submit Action all
\FfMultiline For Multiline text field text
\FfPassword Password field text
\FfNoToggleToOff Used with Radio Buttons Radio only
\FfRadio Radio Button Flag Radio if set
\FfPushButton Push Button Flag Pushbutton
\FfCombo Combo Flag choice
\FfEdit Edit/NoEdit combo
\FfSort Sort List choice
\FfFileSelect File Select (PDF 1.4) text
\FfMultiSelect multiple select (PDF 1.4) choice
\FfDoNotSpellCheck Do not spell check (PDF 1.4) text, combo
\FfDoNotScroll do not scroll (PDF 1.4) text
\FfComb comb field (PDF 1.5) text
\FfRadiosInUnison radios in unison (PDF 1.5) radio
\FfCommitOnSelChange commit on change (PDF 1.5) choice
\FfRichText rich text (PDF 1.5) text
59
C. Supported Key Variables

Below is a list of the keys supported for modifying the appearance or for creating an
action of a field. If the default value of a key is empty, e.g., \Ff{}, then that key does
not appear in the widget. The Acrobat viewer may have a default when any particular
key does not appear, e.g. \W{} will be interpreted as \W{1} by the viewer.
In the past, the value of the \textColor key must include the color model specification:
• g (for gray scale): a single number between 0 and 1; example, \textColor{.5 g}
• rg: Red Green Blue: a list of three numbers between 0 and 1 giving the compo-
nents of color; for example \textColor{.1 .2 .3 rg}
• k Cyan Magenta Yellow [K]Black: a list of four numbers between 0 and 1 giving the
components of the color according to the subtractive model used in most printers;
for example \textColor{.1 .2 .3 .4 k}
In this current version of eforms, the color model can be optionally included. The
eforms package will supply the correct specification as a function of the number of ar-
guments provided. Thus, the examples above can now be written as \textColor{.5},
\textColor{.1 .2 .3}, and \textColor{.1 .2 .3 .4}.
Note: Regarding the keys \textColor, \BG, \BC, and \Color8 , beginning with eforms
dated 2010/07/23 or later, eforms now uses the hycolor package to process all color
keys (listed above); consequently, if the xcolor package is also loaded on your system,
you can use named colors to specify color for the eforms keys. For example, if the
definition was made
\definecolor{myBlue}{rgb}{0.24,0.38,0.68}
then each of the following is valid: \textColor{myBlue} (for specifying text color for
text fields), \BG{myBlue} (for specifying the background color of a field), \BC{myBlue}
(for specifying the border color of a field), and \Color{myBlue} (for specifying the
border color of a link).
8 Information regarding the \Color key may be found in Section 3, page 18. The \Color key is more fully
documented in the rather comprehensive article Support for Links in AeB/eForms posted on the AeB Blog.
60
Supported Key Variables
Key Description Default
Entries common to all annotations:
\F See the annotation F flag Table \F{}
Border Style Dictionary (BS)
\W Width in points around the boundary \W{}

of the field, for example, \W{1}. (same as \W{1})
\S Line style, values are S (solid), D \S{}

(dashed), B (beveled), I (inset), U
(underlined); \S{B}
\AA Additional actions, a dictionary. These \AA{}

actions are triggers by mouse up, (no actions)
mouse down, mouse enter, mouse
exit, on focus, on blur events; for text
and editable combo boxes there is
also the format, keystroke, validate
and calculate events. The various
triggers are discussed in
Trigger Events.
\A Action dictionary, use this to define \A{}

JavaScript actions, as well as other (no action)
actions, for mouse up events. See
Trigger Events for a discussion of the
mouse up event.
\Border Used with link annotations, an array of \Border{0 0 0}

three numbers and an optional dash (no border)
array. If all three numbers are 0, no
border is drawn
\D (link annotations) An array of two

numbers that set the dash pattern of a
link annotation. The default is 3,
which means 3 points of line, 3 points
gap. A value of \D{3 2} means three
points of line, followed by two points
of space.
\AP Appearance dictionary, used mostly in \AP{}

AcroTEX with check boxes to define the

‘On’ value.
61
\AS Appearance state, normally used with \AS{}

check boxes and radio buttons when
there are more than one appearance.
Advanced techniques only.
Entries common to all fields:
\TU Tool tip (PDF 1.3), for example, \TU{}

\TU{Address}. Obeys unicode
option.
\Ff See the Field flag Ff table; e.g. \Ff{}

\Ff{\FfReadOnly} makes the field
read only.
\DV Default value of a field. This is the \DV{}

value that appears when the field is
reset; e.g., \DV{Name:}. Obeys
unicode option.
\V Current value of the field; for example, \V{}

\V{D. P. Story}. Obeys unicode
option.
Entries specific to a widget annotation:
\H Highlight, used in button fields and \H{}

link annotations. Possible values are N (same as \H{I})
(None), P (Push), O (Outline), I (Invert);
e.g., \H{P}.
Appearance Characteristics Dictionary (MK)
\MK A dictionary that contains the keys various

listed below. For all fields the MK has a
template that is filled in using the keys
below; this key is available only for
check boxes and radio buttons.
\R Number of degrees the field is to be \R{}

rotated counterclockwise. Must be a
multiple of 90 degrees; \R{90}.
\BC The boundary color, a list of 0 \BC{}

(transparent), 1 (gray), 3 (RGB) or 4 (transparent)
(CMYK) numbers between 0 and 1. For

example, \BC{1 0 0} is a red border.
62
\BG Background color. Color specification \BG{}

same as \BC (transparent)
\CA Button fields (push, check, radio) The \CA{}

widget’s normal caption; e.g.
\CA{Push}, in the case of a
pushbutton. For check boxes and
radio, the value of \CA is a code that
indicates whether a check, circle,
square, star, etc. is used. These codes
are introduced through
\symbolchoice. Obeys unicode
option.
\RC Pushbutton fields only. The roll over \RC{}

text caption. Obeys unicode option.
\AC Pushbutton fields only. The down \AC{}

button caption. Obeys unicode
option.
\mkIns A variable for introducing into the MK \mkIns{}

dictionary any other key-value pairs
not listed above. Principle examples
are I, RI, IX, IF, TP, which are used
for displaying icons on a button field.
See an example in the demo file
eforms.tex
\I (pushbuttons only) an indirect \I{nIcon}

reference to a form XObject defining (example)
the buttons’s normal icon
\RI (pushbuttons only) an indirect \RI{rIcon}

the buttons’s rollover icon
\IX (pushbuttons only) an indirect \I{dIcon}

the buttons’s down icon
\importIcons (pushbuttons only) a special key to \importIcons{n}

signal that this button is the target of
JavaScript that will supply the icons
faces. Syntax: \importIcons{y|n}

63
\TP {0|1|2|3|4|5|6} (pushbuttons \TP{0}

only; optional) A code indicating the
layout of the text and icon; these
codes are 0 (label only); 1 (icon only);
2 (label below icon); 3 (label above
icon); 4 (label to the right of icon);
5 (label to the left of icon); 6 (label
overlaid on the icon). The default is 0.
\SW {A|B|S|N} (pushbuttons only; \SW{A}

optional) The scale when key.
Permissible values are A (always scale),
B (scale when icon is too big), S (scale
when icon is too small), N (never
scale). The default is A.
\ST {A|P} (pushbuttons only; optional) \ST{P}

The scaling type. Permissible values
are A (anamorphic scaling); P
(proportional scaling). The default is
P.
\PA {num1 num2 } (pushbuttons only; \PA{.5 .5}

optional) The position array. An array
of two numbers, each between 0 and 1
indicating the fraction of left-over
space to allocate at the left and
bottom of the annotation rectangle.
The two numbers should be separated
by a space. The default value,
\PA{.5 .5}, centers the icon in the
rectangle.
\FB {true|false} (pushbuttons only; \FB{false}

optional) The fit bounds Boolean. If
true, the button appearance is scaled
to fit fully within the bounds of the
annotation without taking into
consideration the line width of the
border.
Entries common to fields containing variable text:
\Q {0|1|2|empty} Quadding for text Q{}

fields. Values are 0 (left-justified), 1 (left justified)

(centered), 2 (right-justified); e.g.,
\Q{1}.
64
Default Appearance (DA)
\DA Default appearance string of the text

in the widget. Normally, you just
specify text font, size and color. Can
be redefined, advance techniques
needed.
\textFont {font-spec} Font to be used to \textFont{Helv}

display the text
\textSize {num} The size in points of the text \textSize{9}
\textColor {color-spec} The color of the text. \textColor{0 g}

There are several color spaces,
including grayscale and RGB; for
example, \textColor{1 0 0 rg},
gives a red font. Recent advances in
parsing this command have eliminated
the need to include the color space
specification. Thus,
\textColor{1 0 0} also gives a red
font.
Entries specific to text fields:
\MaxLen {num|empty} The maximum length \MaxLen{}

of the text string input into a text
field. Used also with comb fields to set
the number of combs. Example,
\MaxLeng{15}.
Entries specific to signature fields:
\Lock This key is used to lock fields after the \Lock{}

signature field is signed. Example,
\Lock{/Actions/All}. See
subsection 2.4, page 16 for more
examples.
Specialized, non-PDF Spec commands:
\rawPDF {PDF-KVPs} If all else fails, you can \rawPDF{}

always introduce key-value pairs
through this variable.
65
\autoCenter {y|n} There is a centering code that

attempts to give a pleasant placement
of the field. \autoCenter{n} turn
auto centering off.
\inline {y|n} If \inline{y}, an alternate

method is used get a better vertical
positioning. Designed for inline form
fields. The default is \inline{n}.
\presets {\cmd} This commands takes a

macro as its argument, the text of the
macro are key-value pairs. This is
useful for setting up a series of
presets for fields. Example,
\presets{\myFavFive}
\symbolchoice {symbol-choice} Use this variable

to specify what symbol is to be used
with a check box or radio button.
Possible values are check, circle,
cross, diamond, square and star.
Can be used to globally change the
symbol choice as well; for example,
\symbolchoice{check}, which is the
default value.
\cmd {cmd-args} Passes its argument

into the key-value parsing stream,
refer to page 55 for an example.
\linktxtcolor {named-color|empty} The value of \linktxtcolor

this variable is a named color and is {\@linkcolor}
the color of the link text. Only
recognized in link annotations. A
value of \linktxtcolor{} paints the
text the \normalcolor.
Special link key-values used by aeb_mlink and annot_pro
\mlstrut {strut} Adjusts the height of a \mlstrut{\strut}

multi-line link, e.g.,
\mlstrut{\large\strut}
66
\mlcrackat {num|empty} Used to break a \mlcrackat{}

multi-line link across a page boundary;
specifying \mlcrackat{3} breaks the
link after the 3rd syllable. The
aeb_mlink package then creates two
links consisting of the text up to and
including the crack-at value and the
second link consisting of the rest of
the hypertext link (or url) string.
\mlhyph {y|n} A key that takes ‘y’ or ‘n’ as its \mlhyph{n}

value. If ‘y’ is passed, then a hyphen is
inserted after the break in a multi-line
link that crosses a page boundary.
\mlignore {0|1} An internal switch used in \mlignore{0}

building multi-line links and text
markup annotations that cross page
boundaries. Do not use.
\mlcrackinsat \mlcrackinsat{latex-content} \mlcrackinsat{}

This key inserts its argument after the
hyphen (if there is one) at the point
declared by the \crackat value.
67
References
[1] Core JavaScript Guide, available from Mozilla Developer Center. See page 26.
[2] Core JavaScript Reference available from Mozilla Developer Center. See pages 26
and 50.
[3] Developing Acrobat Applications using JavaScript, available from Acrobat Devel-
oper Center. See pages 26 and 50.
[4] JavaScript for Acrobat API Reference,available from Acrobat Developer Center. See
pages 26 and 50.
[5] PDF Reference, sixth edition, PDF 1.7, available from Acrobat Developer Center.
See pages 22, 23, 24, and 26.

AcroTex Acrobat Javascript

Uploaded by

Copyright:

Available Formats

AcroTex Acrobat Javascript

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

AcroTex Acrobat Javascript

Uploaded by

Copyright:

Available Formats

What are the different types of form fields supported?

What are the different types of form fields supported?

What are some of the options available for the AeB eforms package?

What are some of the options available for the AeB eforms package?

AcroTEX.

Support for AcroForms and Links,

Document JavaScript and Open Page

Copyright © 2019 [email protected]

PDF Links and Forms 4

6 The useui option: A User-Friendly Interface 30

Setting the Tab Order 41

Document and Page JavaScript 45

9 The insDLJS and insDLJS* Environments 45

11 The execJS Environment 52

12 The deﬁneJS Environment 53

B Annotation Field ﬂags Ff 58

C Supported Key Variables 59

PDF Links and Forms

(a) Push Button

(a) List Box

• Core JavaScript Reference at Mozilla Developer Center.

• PDF Blog, by D. P. Story.

• AeB Blog, by D. P. Story.

1. Package Requirement and Options

1.1. Package Requirements

1.2. Package Options

dvipsone, dvips, pdftex, dvipdfm, dvipdfmx, xetex

1.3. The preview option

quicker PDF readers such as sumatraPDF or PDF-Exchange; these non-conforming PDF

\previewOn\pmpvOn % <--enhanced preview activated

real value preview value

1.4. The useui option

1.5. The unicode option of hyperref

The \presets key is useful for developing collections of pre-deﬁned key-value

Later, a button can be created using these preset values:

Later, a button can be created using these preset values:

2.1. Button Fields

#1: optional, used to enter any modiﬁcation of appearance/actions

#3: the width of the bounding rectangle

#4: the height of the bounding rectangle

Default Appearance: The default appearance of a pushbutton is determined by the

Example 2. Button with empty width argument: Push

Refer to the icon-appr package to supply icon appearances to pushbuttons created by

#1: optional, used to enter any modiﬁcation of appearance/actions

#2: the title of the check box button

#3: the width of the bounding rectangle

#4: the height of the bounding rectangle

#5: the name of the “on” state (the export value)

Default Appearance: The default appearance of a standard check box is determined by

#1: optional, used to enter any modiﬁcation of appearance/actions

#2: the title of the radio button

#3: the width of the bounding rectangle

#4: the height of the bounding rectangle

#5: the name of the “on” state (the export value)

2.2. Choice Fields

#1: optional, used to enter any modiﬁcation of appearance/actions

#2: the title of the list box

#3: the width of the bounding rectangle

#4: the height of the bounding rectangle

#5: an array of appearance/values of list.