Some remarks on PDF forms, where textfield contents are calculated automatically.


What I want to do:

Use pdftex to build a PDF form. Input in [text]fields in this form should be used to automatically (i.e. without pressing push buttons or the like) calculate (and present) results in other textfields. Use pre-defined Javascript functions for input validation, textfield formatting and calculation if possible.

Building PDF forms with pdftex is supported (amongst others) by the hyperref package, which I have used in this case.
The example file simple-form.tex [simple-form.pdf] contains a table, where in two rows the input in the first two columns is multiplied and the result show in the third column. The third row gives the sum of the two intermediate results.
Some remarks:
  1. The main point is, that PDF needs to be given a calculation order, in which it should [re]calculate the whole form, if any of the input fields, on which it depends, have been changed. The calculation order (/CO) is an entry in the AcroForm object, so we have to change this object. For hyperref this means to define our own AcroForm object, as there is no interface to it (thanks to Heiko Oberdiek for help with this).
  2. We have to create the AcroForm object before the Form environment starts; otherwise, we get the standard hyperref AcroForm object. Because we can only write out the calculation order behind the Form environment, we use pdftexs reserveobjnum/useobjnum forward referencing mechanism and keep the AcroForm objectnumber for later use in a counter.
  3. Next we need the object numbers for all textfields, where we have set the field's 'calculate' parameter. The PDF objects behind hyperref TextFields are created internally with pdftex's \pdfstartlink command, and up to pdftex 1.30.0 there is no user interface to the object numbers of these objects (at least I don't see it). I uploaded a small patch which implements a \pdflastlink analogous to \pdflastannot and this gives us the possibility to keep the textfields' object numbers. In simple-form.tex a command \addtoCO (thanks to Gert Ingold for help with this) is used to gather all the object numbers in the correct order.
  4. After all fields are defined and the Form environment is closed, we write out the AcroForm object and we are done.
  5. I needed a comb type textfield, which is not yet implemented in the current hyperref package. It's commented out in the example tex source, but you can see a comb in the pdf. You can apply a simple patch [only works with hyperref's pdftex driver] to get an additional comb=[true|false] parameter for the textfields. The patch now also fixes a problem with the border style dictionary: if borderwidth (for textfields) is set to 0, no border is drawn (following the PDF reference) [added 23.8.]. Another boolean parameter 'donotscroll' has been introduced, which when set to true, prevents vertical scrolling in multiline textfields and horizontal scrolling in default textfields. Another remark: the parameter 'borderstyle' is implemented, but not documented in the hyperref manual. borderstyle can be one of [S]olid, [D]ashed, [B]eveled, [I]inset or [U]nderline, with S the default. A dash array is not implemented [added 24.8.].
  6. Acroreader's builtin Javascript functions AFNumber_Keystroke and AFNumber_Format have been used to validate and format the input. I have only been able to set the unicode euro symbol as the currency string in the fields, when omitting hyperref's default resource dictionary entry (/DR ...) from the AcroForm object definition. The builtin AFSimple_Calculate has been used as argument to the textfields' 'calculate'-parameter. A complete documentation of the builtins is not easy to find (thanks for any link!), some info is found in the Acrobat JavaScript Object Specification (and other Adobe manuals), some interesting description of the formatting functions is in the PDFlib manual, but the main source seems to be the Javascript source in the file Aform.js. This has been included in older Acroreader releases in the /plug_ins/JavaScripts directory. For the current Release 7 I don't see a readable file.

This may neither be elegant nor even correct, but it works for me.
Ralf Utermann, 19.8.2005

document history: