AcroTEX.Net eforms and insdljs Documentation

Support for AcroForms and Links, and for

Document JavaScript and Open Page Events

D. P. Story

© 2013 Version 2.0 http://www.acrotex.net January 19, 2013 [email protected] 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 ...... 5 1.5 The unicode option of hyperref ...... 6

2 Form Fields 6 2.1 Button Fields ...... 7 • Push Buttons ...... 7 • Check Boxes ...... 8 • Radio Buttons ...... 9 2.2 Choice Fields ...... 10 • List Boxes ...... 10 • Combo Boxes ...... 11 2.3 Text Fields ...... 13 2.4 Signature Fields ...... 14

3 Link Annotations 17

4 Actions 18 4.1 Trigger Events ...... 18 4.2 Action Types ...... 21

5 JavaScript 25 5.1 Support of JavaScript ...... 25 • The Convenience Command \JS ...... 25 • Inserting Simple JavaScript ...... 25 • Inserting Complex or Lengthy JavaScript ...... 26 5.2 Defining JavaScript Strings with \defineJSStr ...... 27

6 The useui option: A User-Friendly Interface 29 6.1 The Appearance Tab ...... 29 6.2 The Action Tab ...... 35 6.3 The Signed Tab ...... 37

Setting the Tab Order 39

7 Setting the Tab Order 39 7.1 Using \setTabOrderByList ...... 40 7.2 Using \setTabOrderByNumber ...... 41 Table of Contents (cont.) 3

Document and Page JavaScript 43

8 Package Options 43

9 The insDLJS and insDLJS* Environments 43 9.1 What is Document Level JavaScript? ...... 44 9.2 The insDLJS Environment ...... 44 9.3 The insDLJS* Environment ...... 46 9.4 Escaping ...... 47 9.5 Access and Debugging ...... 48 9.6 JavaScript References ...... 49

10 Open Action 49

11 The execJS Environment 50

12 The defineJS Environment 52

Appendices 54

A The Annotation Flag F 54

B Annotation Field flags Ff 55

C Supported Key Variables 56

References 63 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.

• AcroTEX 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 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 it to the driver.

1.3. The preview option Use the preview option if you use a dvi previewer to view your document. When preview is taken, a frame box is drawn around any form field created by eforms, mak- ing the position of the field visible in the previewer. This makes it easy to make any additional adjustments for the position of the field. Turn off this option when you build a PDF file.

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 29, for a description of these key-value pairs. 6

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 in that text field.

2. Form Fields

The eForm support for AcroTEX defines six basic (and internal) commands for creating the six types of form elements. These six are used as “building blocks” for defining all buttons, check boxes, radio buttons and text fields used in the AcroTEX quizzes; and for defining six user-commands: \listBox, \comboBox, \pushButton, \checkBox, \radioButton and \textField. These user commands are the topic of the subsequent sections. 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 \{}. 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}}

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 54. Form Fields 7

2. xkeyval KVP: When the useui option is taken, key-value pairs are defined of the form [ = ]. 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 have a presets key, useful for developing col- lections 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 29.  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: push buttons, check boxes and radio buttons.

• Push Buttons The push button is a button field that has no value, it is neither on or off. Generally, push buttons are used to initiate some action, such as JavaScript action.

\pushButton[#1]{#2}{#3}{#4}

Parameter Description: #1: optional, used to enter any modification of appearance/actions #2: the title of the button field #3: the width of the bounding rectangle #4: the height of the bounding rectangle Default Appearance: The default appearance of a push button is determined by the following: \W{1}\S{B}\F{\FPrint}\BC{0 0 0} \H{P}\BG{.7529 .7529 .7529} Form Fields 8

Key Variables: The first (optional) parameter can be used to modify the default ap- pearance 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 list box: \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{} Example 1. This example resets all forms in this document: \pushButton[\CA{Push}\AC{Me}\RC{Reset}\A{/S/ResetForm}] {myButton}{36bp}{12bp} Example 2. Button with empty width argument: \pushButton[\CA{Push}\AC{Me}\RC{Reset}\A{/S/ResetForm}] {myButton}{}{12bp}

• 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}

Parameter Description: #1: optional, used to enter any modification 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 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 list 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. Form Fields 9

Global Modification: \everyCheckBox{} 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 }

• 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}

Parameter Description:

#1: optional, used to enter any modification 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)  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}

Key Variables: The first (optional) parameter can be used to modify the default ap- pearance 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 list 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: \everyRadioButton{} Form Fields 10

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 }

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}

Parameter Description:

#1: optional, used to enter any modification 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. 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. Form Fields 11

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}

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 (sorts1the 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{} Example 5. List Box (Version 5.0 Required):

\listBox[\autoCenter{n}\DV{1}\V{1} \BG{0.98 0.92 0.73}\BC{0 .6 0} \AA{\AAKeystroke{% 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}

1This 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 12

Parameter Description:

#1: optional, used to enter any modification of appearance/actions

#2: the title of the combo box

#3: the width of the bounding rectangle

#4: the height of the bounding rectangle

#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 combo box is determined by the following:

\W{1}\S{I}\F{\FPrint}\BC{0 0 0}

Key Variables: The first (optional) parameter can be used to modify the default appear- 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 1, page 11). See the Appendix for a complete list of values for the Ff flag. Global Modification: \everyComboBox{} Example 6. Editable combo box (Version 5.0):

\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} Form Fields 13

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}

2.3. Text Fields A text field is the way a user can enter text into a form.

\textField[#1]{#2}{#3}{#4}

Parameter Description:

#1: optional, used to enter any modification of appearance/actions

#2: the title of the text field

#3: the width of the bounding rectangle

#4: the height of the bounding rectangle

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}

Key Variables: The first (optional) parameter can be used to modify the default appear- 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{} Form Fields 14

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,ordvipdfm are used.) Number 1:

Number 2:

Total: 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{% \AAKeystroke{AFNumber_Keystroke(1,1,0,0,"",true)} \AAFormat{AFNumber_Format(1,1,0,0,"",true)}} ]{num.2}{1in}{11bp} \textField[\AA{% \AAKeystroke{AFNumber_Keystroke(1,1,0,0,"",true)} \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}

Parameter Description: #1: optional, used to enter any modification of appearance/actions

#2: the title of the signature field

#3: the width of the bounding rectangle

#4: the height of the bounding rectangle Default Appearance: The default appearance of a standard signature field is deter- mined by the following: \F{\FPrint}\BC{}\BG{}\W{1}\S{S} Form Fields 15

Key Variables: The first (optional) parameter can be used to modify the default appear- 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 \rawPDF. See the Supported Key Variables table for descriptions and notes on each of these variables. Global Modification: \everySigField{} 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: Form Fields 16

"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;orgototheSecurity 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:

• 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 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. 17

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.2

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[]{link text} \setLinkText[]{link text} Both link commands are the same, the use of the second one, \setLink, is discouraged in favor of the use of \setLink. 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 found listed on the AeB Blog page. 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[]{}{} []{}

2The Web package redefines \@linkcolor to be a flavor of green. 18

Parameter Description: The command has five arguments, the first is optional.

1. are optional key-value pairs to change the appearance or action of this link.

2. The parameter is the width of the \parbox.

3. The parameter is the height of the \parbox.

4. The parameter is the positioning parameter of the \parbox (b, c, t).

5. The parameter 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}[b]{\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, 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!")}}}] {myText}{1.5in}{12bp} Actions 19

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!")}}}] {myButton}{30bp}{12bp} 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!")}}] {myButton}{30bp}{12bp} The same code can be performed as follows: \pushButton[\AA{\AAMouseUp{\JS{app.alert("Mouse Up!")}}}] {myButton}{30bp}{12bp} 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: \textField[\AA{\AAOnFocus{\JS{% app.alert("Please enter some data!")}}}] {myText}{1.5in}{12bp} 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!")}}}] {myText}{1.5in}{12bp} 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);}}] {myText}{1.5in}{12bp} 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 code, option- ally defined JavaScript can be used to process the keystroke. The \AAKeystroke Actions 20

key is used within the argument of \AA to define a format 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{% \AAKeystroke{AFNumber_Keystroke(2,0,1,0,"\\u0024",true);} \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: \textField[\AA{% \AAKeystroke{AFNumber_Keystroke(2,0,1,0,"\\u0024",true);} \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{% Actions 21

\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.

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:

\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:

\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 \pushButton[\CA{Go}\AC{Now!}\RC{to Page 3} \A{/S/GoTo/D[\Page3/Fit]}]{myButton1}{}{10bp} Actions 22 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.

\pushButton[\CA{Go}\AC{Now!}\RC{to TOC} \pushButton[\CA{Go}\AC{Now!}\RC{to TOC} \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:

\pushButton[\CA{Go}\AC{Now!}\RC{to Page 3} \A{/S/GoToR/F(webeqtst.pdf)/D[2/Fit]}]{myButton2}{}{10bp}

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:

\pushButton[\CA{Go}\AC{Now!}\RC{to TOC} \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:

\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 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} Actions 23

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).

\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 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. Actions 24

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:

Note: This script no longer works, server-side scripting at the uakron.edu server is no longer premitted (for security reasons). The verbatim lisiting of the code as it used to be when it worked.

\definePath{\URL}{http://www.math.uakron.edu/˜dpstory} \comboBox[\DV{\URL}\V{\URL}\BG{webyellow}\BC{webgreen}] {dest}{1.75inin}{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.

\definePath{\URL}{http://www.math.uakron.edu/˜dpstory} \comboBox[\DV{\URL}\V{\URL}\BG{webyellow}\BC{webgreen}] {dest}{1.75inin}{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} 25

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].

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()}] {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{}}]{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 up3 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

3Other types of possible actions are discussed and illustrated in ‘Actions’ on page 18. JavaScript 26 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. 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 firstn="+n + " 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 52. The example given in Example 6 will suffice; the verbatim listing is reproduced here for convenience. JavaScript 27

 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} 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} 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 26. 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. \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  The demo file definejs.pdf (source definejs.tex) has additional examples of this environment.

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{\}{}

Parameter Description: The parameter \ is a command to be define by \defineJSStr, for example, \myMessage, and is the Java- Script string to be defined as the expansion of the \. 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 \.

• \r (carriage return), \n (line feed) and, \t (tab) can be used to format the message, as desired. JavaScript 28

• 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.}

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 26. 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} var f = this.getField("myCombo"); var a = f.currentValueIndices; if(a==-1) app.alert(@myAlerti); else app.alert(@myAlertii); \end{defineJS} 29

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{% bordercolor={1 0 0},bgcolor={0 1 0}, textcolor={1 0 0},align={right}, uptxt={Push Me}, js={app.alert("AcroTeX rocks!")} }]{pb1}{}{11bp}

You can develop your own set of appearances and use the presets key to conveniently set these. For example, \def\myFavFive{% bordercolor={1 0 0},bgcolor={0 1 0}, textcolor={1 0 0},align={right}, uptxt={Push Me} } Later, a push button can use this preset, like so, \pushButton[\ui{presets=\myFavFive, js={app.alert("AcroTeX rocks!")}}]{pb1}{}{11bp} which produces 4 You can mix your \myFavFive with different key-value pairs, such as a JavaScript action.

6.1. The Appearance Tab We set these key-value pairs to model the user interface of Acrobat. The key is border. In the case of a link, this is the Link Type: Visible Rectangle or Invisible Rectangle. For forms, this key has no counterpart in the user interface. If you set border equal to invisible, that will set border line width to zero \W{0}.

border = visible | invisible

4The reader is reminded once again that the author has no understanding of colors. The useui option: A User-Friendly Interface 30

Command Description: Used with link annotations and determines whether the bor- der surrounding the bounding box of the link is visible. If this key is not specified, the eforms follows the rule: If colorlinks option of hyperref is used, the border is invisible; otherwise, it is visible (and the default linewidth is 1). Use the border key to override this behavior.

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.

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.

bordercolor =

Command Description: The color of the border, when visible, in RGB color space. For example, bordercolor=1 0 0, is the color red.

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.

dasharray = []

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 =

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.

annotflags = hidden | print | -print | noview | lock The useui option: A User-Friendly Interface 31

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.

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 push button and a combo box. The others can be used as appropriate.

maxlength =

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.

tooltip =

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!”

default = value =

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. The useui option: A User-Friendly Interface 32

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”.

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

bgcolor =

Command Description: The background color of a form field. This is a RGB color value.

uptxt = downtxt = rollovertxt =

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. Push buttons only. The following list of keys are used for creating custom appearances on button faces. Acrobat Distiller required for this set. The example files eqforms.tex and eqforms_pro.tex illustrate the creation of icons as button appearances.

normappr = rollappr = downappr =

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.

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.

scalewhen = always | never | iconbig | iconsmall The useui option: A User-Friendly Interface 33

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.

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.

position =

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}.

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 this set. The example files eqforms.tex and eqforms_pro.tex illustrate the creation of these appearances.

appr = { norm={on={},off={normOffAppr}}, down={on={},off={downOffAppr}}, roll={on={},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 useui option: A User-Friendly Interface 34

The down and roll are optional, if you use appr at all, you should specify the norm appearance, both on and off appearances.

align = left | centered | right

Command Description: The type of alignment of a text field. Permitted values are left, centered, and right.

textfont = textsize = textcolor = [ []]

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 = 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.

presets = <\UserCmd>

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 = 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. The useui option: A User-Friendly Interface 35

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 = {

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 recgonized.

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). The useui option: A User-Friendly Interface 36

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.

js = {}

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= {} mousedown= {} onenter= {} onexit= {} onfocus= {} onblur= {} format= {} keystroke= {} validate= {} calculate= {} pageopen= {} pageclose= {} pagevisible= {} pageinvisible= {} The useui option: A User-Friendly Interface 37

Command Description: These are all additional actions (AA) of a form field, taking as their values JavaScript code.

• 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 = {}

Command Description: The lock key is used with signature fields, currently, there is no nice user interface to this key. Typical entries are The useui option: A User-Friendly Interface 38

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.");} 39

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.) Setting the Tab Order 40

• 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.5 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.

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

5http://www.adobe.com/devnet/acrobat/pdfs/PDF3200_2008.pdf Setting the Tab Order 41

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=,title=