Chapter 7. AcroForms

This chapter will go into detail on a special type of annotation: the widget annotation that is the building block for PDF forms.

PDF 1.2 introduced the concept of an interactive form (a collection of fields that can be used to gather information interactively from a user) to the PDF format. There will be at most one single, global form in the PDF; it can contain any number of fields, which can appear on any combination of pages.

Note

Interactive forms should not be confused with form XObjects (discussed in Vector Images). Despite the similarity of their names, the two are different, unrelated types of objects.

The Interactive Form Dictionary

The document’s interactive form is described using an interactive form dictionary, which is the value of the AcroForm key found in the document catalog dictionary.

Note

Because that is the name of the key, the interactive form dictionary is frequently referred to as the AcroForm dictionary and the type of form as an AcroForm.

This dictionary has only one required key, Fields, which specifies an array of field dictionaries that represent the fields in the form. However, there are a few common optional fields that you may need to specify for some of your forms:

DR
When creating the appearance streams for your fields, you may wish to refer to some resources shared by one or more fields. The resource dictionary specified by this key serves to provide that information, much as the page resource dictionary does for page content. If the DR key is present, its value (of type dictionary) needs to include a Font key. The value of Font is the resource name and font to be used as a default font for displaying text in fields.
NeedAppearances
This field should only be present and set to true when one or more fields in the form do not have an appearance stream. It is intended as a clue for a viewer to forceably rebuild such streams; however, many viewers do not respect this. It is therefore recommended to always provide the appearance streams for each field.
XFA
PDF 1.5 introduced a special type of form called XFA (eXtensible Form Architecture) that uses an XML grammar to describe the form rather than native PDF syntax. The value of this key, if present, is an array of XML fragments based on the XFA grammar.

The Field Dictionary

The field dictionary specifies the details of each field in a document’s interactive form. Fields can be organized hierarchically and can inherit attributes from their ancestors in the hierarchy. A field that has children that are fields is called a nonterminal field. A field that does not have children, such as a simple button or text field, is called a terminal field. Child fields are specified in an array of field dictionaries that is the value of a Kids key, while a child’s parent is specified via the Parent key.

Every field has to have a class associated with it via an FT key in the field dictionary (or inherited from a parent field). There are four possible values for the class of a field:

Btn
Button fields, which include push buttons, checkboxes, and radio buttons.
Tx
Text fields into which a user can enter text.
Ch
Choice fields such as scrollable lists, combo boxes, or pop-up menus.
Sig
Signature fields to enable digital signatures for PDF.

Since the purpose of a field is to gather information from a user, it needs a way to store that value. That storage location is the value of the V key in the field dictionary. The type of value and how it relates to the field differs based on the type of field.

While not required, most fields have names associated with them. In fact, a field can have up to three different names, each used in a different context.

The T key in the field dictionary consists of a text string value that defines the field’s partial field name. A field’s fully qualified name is never explicitly defined in the PDF but instead is dynamically constructed from the partial field names of the field and all of its ancestors. For a field with no parent, the partial and fully qualified names are the same. For a field that is the child of another field, the fully qualified name is constructed by appending the child field’s partial name to the parent’s fully qualified name, separated by a period (2Eh). Because the period is used as a separator for fully qualified names, a partial name cannot contain a period character.

Note

For example, if a field with the partial field name UserInfo has a child whose partial name is Address, which in turn has a child with the partial name ZipCode, the fully qualified name of this last field is UserInfo.Address.ZipCode.

When preparing a PDF that may be processed by a screen reader or other assistive technology, it is important to provide a TU key for each field. The value of this key is a text string that is used instead of the field’s partial or fully qualified name to identify it to the user.

The third name that a field might have is its export name—a name used when exporting the data to a file. The TM key’s string value will be exported as the name that is associated with the field’s value when it is exported to various formats. If not present, then the field’s partial name will be used.

A field dictionary may contain (or may inherit) an Ff key whose value is an unsigned 32-bit integer composed of a series of “bit flags” or “bit positions” that specify various characteristics of the field. These bit positions within the flag word are numbered from 1 (low-order) to 32 (high-order). There are three flags (listed in Table 7-1) that are common to all classes of fields, but there are also many flags that apply only to specific field classes. All undefined flag bits are considered reserved and are set to 0 by a PDF writer.

Table 7-1. Standard field flags
Bit position Name Meaning

1

ReadOnly

If set, the user may not change the value of the field. This flag is useful for fields whose values are computed or imported from a database.

2

Required

If set, the field must have a value at the time it is exported by a SubmitForm action.

3

NoExport

If set, the field may not be exported by a SubmitForm action.

One thing that hasn’t been mentioned yet is how to define which page the field belongs on and where to draw it on the page. The field dictionary does not provide for any keys that would define these things, whereas the annotation dictionary that we learned about in Annotation Dictionaries does. As such, we are going to combine these two things to solve our problem.

A widget annotation is created for each field that is to be drawn, and then associated (as with any other annotation) to the page on which it will appear. This means that a single dictionary will contain keys from both a field dictionary and an annotation dictionary. If the field is the parent of a group (such as a radio button group), and the grouping itself has no visual representation and is therefore not drawn on a page, then it will be a standard field dictionary without any annotation extras.

Note

This merged dictionary is only necessary/required for any form field that will be displayed on a page.

Example 7-1 shows a widget annotation that includes both annotation information (e.g., Rect, AP) and field information (e.g., FT, Ff).

Example 7-1. Example field and widget annotation
16 0 obj
<<
    /F 4
    /Type /Annot
    /Rect [27.014 749.644 99.014 769.644]
    /FT /Btn
    /Ff 65536
    /Subtype /Widget
    /T (PushButton)
    /AP << /N 42 0 R >>
>>
endobj

Field Classes

As mentioned earlier, every field must have a class associated with it. The field types include button, text, choice, and signature fields.

A button field represents an interactive control or element on the page that the user can “press” with a mouse or other pointing device. There are three types of button fields (see Figure 7-1):

Pushbutton
A field with the Pushbutton bit set to 1 that does not have any value (and thus no V key in its dictionary)
Checkbox
A field that toggles between two states, on and off, and has both the Pushbutton and RadioButton flags clear. The states refer to the names of the appearance streams associated with the field and are also the name value(s) for the V key.
Radio button
One of a set of related buttons, of which only one can be on at a time. As with checkboxes, each button can have two states (on and off), and they are used in the same way. These fields will have the Pushbutton flag clear but the RadioButton flag set.

For button fields, bits 15, 16, 17, and 26 of the field flags indicate the intended behavior, as described in Table 7-2.

Table 7-2. Button field flags
Bit position Name Meaning

15

NoToggleToOff (radio buttons only)

If set, exactly one radio button shall be selected at all times; selecting the currently selected button has no effect. If clear, clicking the selected button deselects it, leaving no button selected.

16

Radio

If set, the field is a set of radio buttons; if clear, the field is a checkbox. This flag may be set only if the Pushbutton flag is clear.

17

Pushbutton

If set, the field is a pushbutton that does not retain a permanent value.

26

RadiosInUnison

If set, a group of radio buttons within a radio button field that use the same value for the on state will turn on and off in unison; that is, if one is checked, they are all checked. If clear, the buttons are mutually exclusive (the same behavior as HTML radio buttons).

Examples of all three types of buttons
Figure 7-1. Example buttons
% Document catalog
12 0 obj
<<
    /Metadata 2 0 R
    /Type /Catalog
    /Pages 9 0 R
    /AcroForm 22 0 R
    /Outlines 6 0 R
>>
endobj

% AcroForm dictionary
22 0 obj
<<
    /Fields [16 0 R 17 0 R 24 0 R]
>>
endobj

% Pushbutton field
16 0 obj
<<
    /F 4
    /Type /Annot
    /Rect [27.014 749.644 99.014 769.644]
    /FT /Btn
    /Ff 65536
    /Subtype /Widget
    /T (PushButton)
    /AP << /N 42 0 R >>
>>
endobj

% Checkbox field
17 0 obj
<<
    /Type /Annot
    /Rect [27.014 715.314 45.014 733.314]
    /FT /Btn
    /AS /Off         % default state is Off (unchecked)
    /Subtype /Widget
    /F 4
    /T (CheckBox)
    /AP <<
        /N << /Yes 38 0 R /Off 37 0 R >>
        /D << /Yes 41 0 R /Off 40 0 R >>
    >>
>>
endobj

% Radio button #3
18 0 obj
<<
    /F 4
    /Rect [27.014 682.711 45.014 700.711]
    /Parent 24 0 R    % this is the radio button group...
    /AS /Off          % default state is Off (unchecked)
    /Subtype /Widget
    /Type /Annot
    /AP <<
        /N << /2 33 0 R /Off 34 0 R >>
        /D << /2 35 0 R /Off 36 0 R >>
    >>
>>
endobj

% Radio button #2
20 0 obj
<<
    /F 4
    /Rect [48.7541 682.711 66.7541 700.711]
    /Parent 24 0 R    % this is the radio button group...
    /AS /Off          % default state is Off (unchecked)
    /Subtype /Widget
    /Type /Annot
    /AP <<
        /N << /1 29 0 R /Off 30 0 R >>
        /D << /1 31 0 R /Off 32 0 R >>
    >>
>>
endobj

% Radio button #1
21 0 obj
<<
    /F 4
    /Type /Annot
    /Rect [73.1377 682.711 91.1377 700.711]
    /Parent 24 0 R    % this is the radio button group...
    /AS /0            % default state is 0, which is On
    /Subtype /Widget
    /AP <<
        /N << /0 25 0 R /Off 26 0 R >>
        /D << /0 27 0 R /Off 28 0 R >>
    >>
>>
endobj

% this is the radio button grouping field
24 0 obj
<<
    /Kids [21 0 R 20 0 R 18 0 R]
    /FT /Btn
    /Opt [(RadioButton1) (RadioButton1) (RadioButton1)]
    /Ff 49152
    /T (RadioButton)
>>
endobj

Text fields are areas on the page where arbitrary text/strings can be entered either by a user or programmatically by software. The text is normally only drawn in a single font, size, and color along a single line; however, various flags and additional keys can be supplied in the field dictionary to enable the text to span multiple lines (wrapping accordingly), or use rich text formatting, or both. Figure 7-2 shows a few examples.

Sample Plain and RichText fields
Figure 7-2. Text fields

The text string (or stream) that represents the value of the field is stored as the value of the V key in the field dictionary. When creating the appearance for the field, the text is normally drawn in a single style (font, size, color, and so forth), which is defined by the value of the DA key. Example 7-2 shows a few examples of text fields.

Example 7-2. Simple text fields
16 0 obj
<<
    /DA (/Helv 12 Tf 0 g)
    /F 4
    /FT Tx
    /Rect [ 9.526760 680.078003 297.527008 702.078003 ]
    /Subtype /Widget
    /Type /Annot
    /T (SimpleText)
    /V (A single line of text in one style)
>>
endobj

17 0 obj
<<
    /DA /Helv 12 Tf 0 g
    /F 4
    /FT Tx
    /Ff 4096
    /Rect [ 8.184650 550.416992 296.184998 653.090027 ]
    /Subtype /Widget
    /Type /Annot
    /T (MultilineText)
    /V (Multiple lines of text in a single style will automatically wrap
        around from line to line as more text is added to a second paragraph)
>>
endobj

If the text value of the field should be displayed in multiple styles, then a rich text string is provided as the value of the RV key in the field dictionary and bit 26 of the text field flags should be set. A rich text string is a fully formed XML document that conforms to the grammar defined for rich text in the XFA specification, which is based on specific subsets of the XHTML 1.0 and CSS2 standards.

The <body> element is the root of the document, which is then divided up into paragraphs (<p>) and spans (<span>) that are styled using standard CSS attributes such as font-family and color. Example 7-3 shows an example of a rich text field.

Example 7-3. A rich text field
20 0 obj
<<
    /F 4
    /FT Tx
    /Ff 33554432
    /Rect [ 312.427002 680.749023 600.427002 702.749023 ]
    /Subtype /Widget
    /Type /Annot
    /T (RichText)
    /V (A single line of text in multiple styles)
    /RV (<?xml version="1.0"?> \
        <body xfa:APIVersion="Acroform:2.7.0.0" xfa:spec="2.1" \
        xmlns="http://www.w3.org/1999/xhtml" \
        xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"><p \
        style="margin-top:0pt;margin-bottom:0pt;text-valign:top;font- \
        family:Helvetica;font-size:13pt"><span>A </span><span \
        style="font-weight:bold">single</span><span \
        style="font-weight:normal"> </span><span \
        style="font-weight:normal;text-decoration:underline">line</span>< \
        span style="font-weight:normal;text-decoration:none"> \
        </span><span \
        style="color:#0000ff;font-weight:normal;text-decoration:none">of< \
        /span><span \
        style="color:#000000;font-weight:normal;text-decoration:none"> \
        </span><span \
        style="color:#000000;font-weight:normal;font-style:italic;text- \
        decoration:none">text</span><span \
        style="color:#000000;font-weight:normal;font-style:normal;text- \
        decoration:none"> </span><span \
        style="vertical-align:4.03pt;font-size:8.58pt;color:#000000;font- \
        weight:normal;font-style:normal;text-decoration:none">in</span>< \
        span \
        style="vertical-align:baseline;color:#000000;font-weight:normal; \
        font-style:normal;text-decoration:none"> </span><span \
        style="vertical-align:baseline;color:#00ff00;font-weight:normal; \
        font-style:normal;text-decoration:none">multiple</span><span \
        style="vertical-align:baseline;color:#000000;font-weight:normal; \
        font-style:normal;text-decoration:none"> styles</span></p></body>)
>>
endobj


21 0 obj<<
    /F 4
    /FT Tx
    /Ff 33558528
    /Rect [ 311.756012 550.416992 599.755981 653.090027 ]
    /Subtype /Widget
    /Type /Annot
    /T (MultilineRichText)
    /V (Multiple lines of text, in multiple styles,\
        automatically wrap around from line to line as more text is added. \
        A second, centered, paragraph)
    /RV (<?xml version="1.0"?>
    <body xfa:APIVersion="Acroform:2.7.0.0" xfa:spec="2.1" \
    xmlns="http://www.w3.org/1999/xhtml" \
    xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"><p \
    style="margin-top:0pt;margin-bottom:0pt;font-family:Helvetica;font- \
    size:13pt"><span>Multiple </span><span \
    style="text-decoration:underline">lines</span><span \
    style="text-decoration:none"> of </span><span \
    style="font-style:italic;text-decoration:none">text,</span><span \
    style="font-style:normal;text-decoration:none"> in </span><span \
    style="color:#00ff00;font-style:normal;text-decoration:none">multiple \
    styles</span><span \
    style="color:#000000;font-style:normal;text-decoration:none">, that \
    will automatically </span><span \
    style="color:#000000;font-weight:bold;font-style:normal;text- \
    decoration:none">wrap</span><span \
    style="color:#000000;font-weight:normal;font-style:normal;text- \
    decoration:none"> around from </span><span \
    style="color:#000000;font-weight:normal;font-style:normal;text- \
    decoration:line-through">line to line</span><span \
    style="color:#000000;font-weight:normal;font-style:normal;text- \
    decoration:none"> as </span><span \
    style="color:#ff0000;font-weight:normal;font-style:normal;text- \
    decoration:none">more text</span><span \
    style="color:#000000;font-weight:normal;font-style:normal;text- \
    decoration:none"> is added.</span></p><p \
    style="margin-top:0pt;margin-bottom:0pt;font-family:Helvetica;font- \
    size:13pt"> </p><p \
    style="margin-top:0pt;margin-bottom:0pt;text-align:center;font-family \
    :Helvetica;font-size:13pt"><span>A second, centered, \
    paragraph</span></p></body>)
>>
endobj

ISO 32000-1, Table 228 lists all of the field flags that can be specified on a text field, but the most commonly used are the following:

Bit 13
The multiline flag is set when the text value of the field should be wrapped to the rect of the annotation.
Bit 14
The password flag specifies that the value of this field is never to be drawn nor stored in the PDF, but only maintained locally for the purposes of data submission.
Bit 26
The rich text flag specifies that the value of this field is not just a simple string, but is actually richly styled text.

A choice field is used to present a user with a choice of multiple options from which she can select one or more to become the value of the field.

Normally a choice field only allows a single item in the list of options/choices to be chosen by the user. However, there are times when the selection of multiple items can be useful. To enable this, the multiselect flag (bit 22) of the field flags is set.

The list of text strings that will be displayed in the field as the choices from which the user can select are stored in an array as the value of the Opt key in the field dictionary. In most cases, the array is a simple array of just text strings; however, if the export name of a given text string needs to be different, then that element of the array will itself be an array of two elements—the text string to be displayed followed by the export name. Example 7-4 illustrates both approaches.

Example 7-4. Examples of options
% Simple options
/Opt [ (France) (Belgium) (Germany) (United Kingdom) (Spain) ]

% Options with alternate export names
/Opt [ (France) (Belgium) [(Germany) (DE)] [(United Kingdom) (UK)] (Spain) ]

The value, as with other field types, is stored as the value of the V key in the field dictionary. However, when the multiselect flag is set, the value is of type array instead of a text string.

Note

The value of V may also be of type null, which is the default, to indicate that nothing has been chosen from the options.

The list of selected items will be stored as the value of the I key in the field dictionary. The value will consist of a list of integers representing the (zero-based) indices of the items that are selected. Normally this is used only for fields with the multiselect flag set, but it can be used for single-selection fields as well.

Note

If the items listed in the value of I differ from those in value of V in the field dictionary, the V entry will take precedence.

The default type of choice field is the scrolling list (Example 7-5), which displays the list of items in a scrollable (if there are too many to show all at once) list. A user can either have nothing selected or at least one item selected.

Example 7-5. Scrolling list
a scrolling list field
16 0 obj
<<
    /DV (Prune)        % the default value if another is not specified
    /F 4
    /FT Ch
    /I [ 2 ]
        /Opt [ (Orange) (Apple) (Banana) (Pear) (Melon) (Grapefruit) (Cherry)
               (Grape) (Prune) ]
    /Rect [ 59.053501 606.116028 275.135986 716.169983 ]
    /Subtype /Widget
    /T (ListBox)
    /Type /Annot
    /V (Banana)
>>
endobj

Rather than taking up a lot of the page with the full list of items, they can instead be presented in a smaller combo box from which the users can select the items they wish (Example 7-6). If bit 18 of the field flags is set, the choice field will be presented as a combo box.

Example 7-6. Combo box
a Combo box field
17 0 obj
<<
    /DV (California)
    /F 4
    /FT Ch
    /Ff 131072
    /I [ 4 ]
    /Opt [ (Alabama) (Alaska) (Arizona) (Arkansas) (California) (Connecticut)
           (Colorado) ]
    /Rect [ 341.571014 682.617004 526.112976 715.499023 ]
    /Subtype /Widget
    /T (Dropdown)
    /Type /Annot
    /V (California)
>>
endobj

Sometimes it is not possible to include all the possible choices in a list, and it will be necessary for the users to enter their own values (Example 7-7). Setting bit 19 of the field flags makes the value of the combo box editable.

Example 7-7. Editable combo box
an editable Combo box field
<<
    /DV (Germany)
    /F 4
    /FT Ch
    /Ff 393216
    /Opt [ (France) (Belgium) (Germany) (United Kingdom) (Spain) ]
    /Rect [ 342.242004 606.116028 526.783997 638.997986 ]
    /Subtype /Widget
    /T (DropdownE)
    /Type /Annot
    /V (Slovakia)
>>

A signature field provides a way to identify that a user should apply a digital or electronic signature to the PDF (see Figure 7-3). As such, the field can be thought of as being either signed or not signed. A signed signature field will have a V key in its field dictionary.

Some signature fields
Figure 7-3. Two signature fields

Prior to the user actually signing the field, it serves as a placeholder on the page for where the graphical representation of the signature (if present) will be drawn, along with any information about the type of signature technologies that should be used at the time of signing.

Note

Signature fields that are not intended to be visible will have an annotation rectangle that has zero height and width or have either the Hidden bit or the NoView bit of the F key in their annotation dictionaries set.

The actual process of digitally signing or verifying a PDF is very complex and beyond the scope of this book. If you wish to read more about it, I highly recommend Bruno Lowagie’s “Digital Signatures for PDF Documents”.

Form Actions

In addition to the navigational actions, there are three types of actions that are specific to form fields: SubmitForm, ResetForm, and ImportData. Just as the navigational actions can be associated with bookmarks or links, these form-related actions can be as well. However, it is more common to associate them with a button field on the form.

The SubmitForm action informs the PDF viewer to transmit the names and values of the specified fields to the specified URL in the specified format. This information is provided in the action dictionary, whose S key will have a value of SubmitForm.

The URL where the form data will be submitted is specified as a URL file specification, which is the value of the F key in the action dictionary.

The fields that are to be included in the submitted data are specified in the array value of the Fields key. Each element of the array can be either an indirect reference to a field dictionary or a text string representing the fully qualified name of a field. Elements of both kinds may be mixed in the same array.

Note

The Fields key is not required. If it is not present, that means that all fields of the form will be submitted.

PDF provides the specification of four different formats in which the form data can be submitted to the specified URL. The choice of format is determined by a series of flags that are specified as the value of the Flags key of the action dictionary:

FDF
The Forms Data Format (FDF) is a subset of the PDF syntax that can be used to represent form data. It is described in ISO 32000-1, 12.7.7 and is the default format for data submission. To use this format, be sure that bits 3 (ExportFormat), 6 (XFDF), and 9 (SubmitPDF) are clear.
HTML
This is the same format that HTML 4.01 uses to submit form data. To use this format, set bit 3 (ExportFormat) and be sure to keep bits 6 (XFDF) and 9 (SubmitPDF) clear.
XFDF
The XML Forms Data Format (XFDF) is a version of FDF based on XML. XFDF is described in an Adobe technical note. To use this format, set bit 6 (XFDF) and be sure to keep bits 3 (ExportFormat) and 9 (SubmitPDF) clear.
PDF
With this format, the entire document is submitted rather than individual fields and values. To use this format, set bit 9 (SubmitPDF) and be sure to keep bits 3 (ExportFormat) and 6 (XFDF) clear.

Example 7-8 shows an example SubmitForm action.

Example 7-8. SubmitForm action
<<
    /F 4
    /FT Btn
    /Ff 65536
    /Rect [ 358.347992 725.026001 430.347992 745.026001 ]
    /Subtype /Widget
    /T (Submit)
    /Type /Annot
    /A <<
        /S SubmitForm
        /Fields [ (Address) (By) (Date) (Email) (Name) (TelNum) (Title) ]
        % since there is no *Flags* key that means use the default, FDF
    >>
>>

The ResetForm action is quite similar to the SubmitForm action in that it operates on a list of fields provided in the Fields key of the action dictionary. However, instead of the PDF viewer submitting the data of the specified fields to a specified URL, the value (V) of each field is reset to the value of its DV (Default Value) key. The S key in the action dictionary will have a value of ResetForm.

If present, the value of the Flags key can be only 0 or 1. A value of 0 (or the key not being present) means that the list of fields in Fields are the fields that should be reset. A value of 1 means that these are the fields that should not be reset (and to reset all others). Example 7-9 illustrates the latter approach.

Example 7-9. ResetForm action
<<
    /A <<
        /Fields [ (By_2) (Date_2) (Email_2) (Name_2) (TelNum_2) (Title_2) ]
        /Flags 1    % reset all BUT these...
        /S ResetForm
    >>
    /F 4
    /FT Btn
    /Ff 65536
    /Rect [ 447.501007 725.026001 519.500977 745.026001 ]
    /Subtype /Widget
    /T (Reset)
    /Type /Annot
>>

The ImportData action enables the importing of the data from a specified FDF file into the fields of the PDF. The action dictionary has two required keys: the S key (with the value of ImportData) and the F key, whose value is a file specification dictionary indicating where the FDF data resides. It can be any type of file specification, including a URL file specification (see URL File Specifications).

What’s Next

In this chapter, you learned about a special type of annotation, the widget annotation, which is the building block for PDF forms. Next you will learn about how to embed files in a PDF.