PDF Reference sixth edition, Adobe Portable Document Format Version 1.7 (book 2) — page 3
683
SECTION 8.6
Interactive Forms
Rich text strings are specified by the RV entry of variable text form field dictionar-
ies (see Table 8.71) and the RC entry of markup annotation dictionaries (see Table
8.21). Rich text strings may be packaged as text streams (see Section 3.8.2, “Text
Streams”). Form fields using rich text streams should also have the RichText flag
set (see Table 8.77).
A default style string is specified by the DS entry for free text annotations (see Ta-
ble 8.25) or variable text form fields (see Table 8.71). This string specifies the de-
fault values for style attributes, which are used for any style attributes that are not
explicitly specified for the annotation or field. All attributes listed in Table 8.74
are legal in the default style string. This string, in addition to the RV or RC entry, is
used to generate the appearance. The following entries are ignored by PDF 1.5-
compliant viewers: the Contents entry for annotations, the DA entry for free text
annotations, and the V, DA, and Q entries for form fields.
Note: Markup annotations other than free text annotations (see “Markup Annota-
tions” on page 616) do not use a default style string because their appearances are
implemented using platform controls requiring the viewer application to pick an ap-
propriate system font for display.
When a form field or annotation contains rich text strings, the flat text (character
data) of the string should also be preserved (in the V entry for form fields and the
Contents entry for annotations). This enables older viewer applications to read
and edit the data (although with loss of formatting information). The DA entry
should be written out as well when the file is saved.
If a document containing rich text strings is edited in a viewer that does not sup-
port PDF 1.5, the rich text strings remain unchanged (because they are unknown
to the viewer), even though the corresponding flat text may have changed. When
a viewer that supports PDF 1.5 reads a rich text string from a document, it must
check whether the corresponding flat text has changed by using the following
procedure:
1. Create a new flat text string containing the character data from the rich text
string. Character references (such as ) should be converted to their char-
acter equivalents.
Note: No attempt should be made to preserve formatting specified with markup
elements. For example, although the <p> element implies a new line, a carriage
return should not be generated in the associated flat text.
684
CHAPTER 8
Interactive Features
2. If either of the values uses UTF-16 encoding, promote the other value to UTF-
16 if necessary.
3. Compare the resulting strings.
If the strings are unequal, it is assumed the field has been modified by an older
viewer, and a new rich text string should be created from the flat text.
When a rich text string specifies font attributes, the viewer application should use
font name selection as described in section 15.3 of the CSS2 specification (see the
Bibliography). It is strongly recommended that precedence be given to the fonts
in the default resources dictionary, as specified by the DR entry in Table 8.67; see
Implementation note 120 in Appendix H.
The following example illustrates the entries in a widget annotation dictionary
for rich text. The DS entry specifies the default font. The RV entry contains two
paragraphs of rich text: the first paragraph specifies bold and italic text in the de-
fault font; the second paragraph changes the font size.
Example 8.15
/DS (font: 18pt Arial)
% Default style string using an abbreviated font
% descriptor to specify 18pt text using an Arial font
/RV (<?xml version="1.0"?><body xmlns="http://www.w3.org/1999/xtml"
xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"
xfa:contentType="text/html" xfa:APIVersion="Acrobat:8.0.0" xfa:spec="2.4">
<p style="text-align:left">
<b>
<i>
Here is some bold italic text
</i>
</b>
</p>
<p style= "font-size:16pt">
This text uses default text state parameters but changes the font size to 16.
</p>
</body> )
685
SECTION 8.6
Interactive Forms
8.6.3
Field Types
Interactive forms support the following field types:
• Button fields represent interactive controls on the screen that the user can
manipulate with the mouse. They include pushbuttons, check boxes, and radio
buttons.
• Text fields are boxes or spaces in which the user can enter text from the key-
board.
• Choice fields contain several text items, at most one of which may be selected as
the field value. They include scrollable list boxes and combo boxes.
• Signature fields represent electronic signatures for authenticating the identity of
a user and the validity of the document’s contents.
The following sections describe each of these field types in detail. Further types
may be added in the future.
Button Fields
A button field (field type Btn) represents an interactive control on the screen that
the user can manipulate with the mouse. There are three types of button fields:
• A pushbutton is a purely interactive control that responds immediately to user
input without retaining a permanent value (see “Pushbuttons” on page 686).
• A check box toggles between two states, on and off (see “Check Boxes” on page
686).
• Radio button fields contain a set of related buttons that can each be on or off.
Typically, at most one radio button in a set may be on at any given time, and se-
lecting any one of the buttons automatically deselects all the others. (There are
exceptions to this rule, as noted in “Radio Buttons” on page 688.)
The various types of button fields are distinguished by flags in the Ff entry, as
shown in Table 8.75.
686
CHAPTER 8
Interactive Features
TABLE 8.75 Field flags specific to button fields
BIT POSITION
NAME
MEANING
15
NoToggleToOff
(Radio buttons only) If set, exactly one radio button must be selected at all
times; clicking 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 check box.
This flag is meaningful 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
(PDF 1.5) 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 ex-
clusive (the same behavior as HTML radio buttons).
Pushbuttons
The simplest type of field is a pushbutton field, which has a field type of Btn and
the Pushbutton flag (see Table 8.75) set. Because this type of button retains no
permanent value, it does not use the V and DV entries in the field dictionary (see
Table 8.69 on page 675).
Check Boxes
A check box field represents one or more check boxes that toggle between two
states, on and off, when manipulated by the user with the mouse or keyboard. Its
field type is Btn and its Pushbutton and Radio flags (see Table 8.75) are both clear.
Each state can have a separate appearance, which is defined by an appearance
stream in the appearance dictionary of the field’s widget annotation (see Section
8.4.4, “Appearance Streams”). The appearance for the off state is optional but, if
present, must be stored in the appearance dictionary under the name Off. The
recommended (but not required) name for the on state is Yes.
The V entry in the field dictionary (see Table 8.69 on page 675) holds a name ob-
ject representing the check box’s appearance state, which is used to select the ap-
propriate appearance from the appearance dictionary.
Example 8.16 shows a typical check box definition.
687
SECTION 8.6
Interactive Forms
Example 8.16
1 0 obj
<< /FT /Btn
/T ( Urgent )
/V /Yes
/AS /Yes
/AP << /N << /Yes 2 0 R /Off
3 0 R>>
>>
endobj
2 0 obj
<< /Resources 20 0 R
/Length 104
>>
stream
q
0 0 1 rg
BT
/ZaDb 12 Tf
0 0 Td
( 8 ) Tj
ET
Q
endstream
endobj
3 0 obj
<< /Resources 20 0 R
/Length 104
>>
stream
q
0 0 1 rg
BT
/ZaDb 12 Tf
0 0 Td
( 8 ) Tj
ET
Q
endstream
endobj
688
CHAPTER 8
Interactive Features
Beginning with PDF 1.4, the field dictionary for check boxes and radio buttons
contains an optional Opt entry (see Table 8.76), which holds an array of text
strings representing the export value of each annotation in the field. It is used for
the following purposes:
• To represent the export values of check box and radio button fields in non-Lat-
in writing systems. Because name objects in the appearance dictionary are lim-
ited to PDFDocEncoding, they cannot represent non-Latin text.
• To allow radio buttons or check boxes to be checked independently, even if
they have the same export value.
An example is a group of check boxes that are duplicated on more than one
page, and the desired behavior is that when a user checks a box, the corre-
sponding boxes on each of the other pages is also checked. In this case, each of
the corresponding check boxes is a widget in the Kids array of a check box field.
Note: For radio buttons, the same behavior occurs only if the RadiosInUnison flag
is set. If it is not set, at most one radio button in a field can be set at a time. See
implementation note 121 in Appendix H.
TABLE 8.76 Additional entry specific to check box and radio button fields
KEY
TYPE
VALUE
Opt
array of
(Optional; inheritable; PDF 1.4) An array containing one entry for each widget annota-
text strings tion in the Kids array of the radio button or check box field. Each entry is a text string
representing the on state of the corresponding widget annotation.
When this entry is present, the names used to represent the on state in the AP dictionary
of each annotation are computer-generated numbers equivalent to the numerical posi-
tion (starting with 0) of the annotation in the Kids array. This allows distinguishing be-
tween the annotations even if two or more of them have the same value in the Opt array.
For example, two radio buttons may have the same on state, but if the RadiosInUnison
flag is not set, only one of them at a time can be checked by the user.
Radio Buttons
A radio button field is a set of related buttons. Like check boxes, individual radio
buttons have two states, on and off. A single radio button may not be turned off
directly but only as a result of another button being turned on. Typically, a set of
radio buttons (annotations that are children of a single radio button field) have at
689
SECTION 8.6
Interactive Forms
most one button in the on state at any given time; selecting any of the buttons au-
tomatically deselects all the others.
Note: An exception occurs when multiple radio buttons in a field have the same on
state and the RadiosInUnison flag is set. In that case, turning on one of the buttons
turns on all of them.
The field type is Btn, the Pushbutton flag (see Table 8.75 on page 686) is clear, and
the Radio flag is set. This type of button field has an additional flag, NoToggle-
ToOff, which specifies, if set, that exactly one of the radio buttons must be select-
ed at all times. In this case, clicking the currently selected button has no effect; if
the NoToggleToOff flag is clear, clicking the selected button deselects it, leaving
no button selected.
The Kids entry in the radio button field’s field dictionary (see Table 8.69 on page
675) holds an array of widget annotations representing the individual buttons in
the set. The parent field’s V entry holds a name object corresponding to the ap-
pearance state of whichever child field is currently in the on state; the default val-
ue for this entry is Off. Example 8.17 shows the object definitions for a set of radio
buttons.
Example 8.17
10 0 obj
% Radio button field
<< /FT /Btn
/Ff
…
% … Radio flag = 1, Pushbutton = 0…
/T ( Credit card )
/V /MasterCard
/Kids [
11 0 R
12 0 R
]
>>
endobj
11 0 obj
% First radio button
<< /Parent 10 0 R
/AS /MasterCard
/AP << /N << /MasterCard
8 0 R
/Off
9 0 R
>>
>>
>>
endobj
690
CHAPTER 8
Interactive Features
12 0 obj
% Second radio button
<< /Parent 10 0 R
/AS /Off
/AP << /N << /Visa 8 0 R
/Off
9 0 R
>>
>>
>>
endobj
8 0 obj
% Appearance stream for "on" state
<< /Resources 20 0 R
/Length 104
>>
stream
q
0 0 1 rg
BT
/ZaDb 12 Tf
0 0 Td
( 8 ) Tj
ET
Q
endstream
endobj
9 0 obj
% Appearance stream for "off" state
<< /Resources 20 0 R
/Length 104
>>
stream
q
0 0 1 rg
BT
/ZaDb 12 Tf
0 0 Td
( 4 ) Tj
ET
Q
endstream
endobj
Like a check box field, a radio button field can use the optional Opt entry in the
field dictionary (PDF 1.4) to define export values for its constituent radio buttons,
691
SECTION 8.6
Interactive Forms
using Unicode encoding for non-Latin characters (see Table 8.76). Opt holds an
array of text strings corresponding to the widget annotations representing the in-
dividual buttons in the field’s Kids array.
Text Fields
A text field (field type Tx) is a box or space in which the user can enter text from
the keyboard. The text may be restricted to a single line or may be permitted to
span multiple lines, depending on the setting of the Multiline flag in the field dic-
tionary’s Ff entry. Table 8.77 shows the flags pertaining to this type of field.
TABLE 8.77 Field flags specific to text fields
BIT POSITION
NAME
MEANING
13
Multiline
If set, the field can contain multiple lines of text; if clear, the field’s text is
restricted to a single line.
14
Password
If set, the field is intended for entering a secure password that should not
be echoed visibly to the screen. Characters typed from the keyboard
should instead be echoed in some unreadable form, such as asterisks or
bullet characters.
To protect password confidentiality, viewer applications should never
store the value of the text field in the PDF file if this flag is set.
21
FileSelect
(PDF 1.4) If set, the text entered in the field represents the pathname of a
file whose contents are to be submitted as the value of the field.
23
DoNotSpellCheck
(PDF 1.4) If set, text entered in the field is not spell-checked.
24
DoNotScroll
(PDF 1.4) If set, the field does not scroll (horizontally for single-line fields,
vertically for multiple-line fields) to accommodate more text than fits
within its annotation rectangle. Once the field is full, no further text is ac-
cepted.
25
Comb
(PDF 1.5) Meaningful only if the MaxLen entry is present in the text field
dictionary (see Table 8.78) and if the Multiline, Password, and FileSelect
flags are clear. If set, the field is automatically divided into as many equally
spaced positions, or combs, as the value of MaxLen, and the text is laid out
into those combs.
26
RichText
(PDF 1.5) If set, the value of this field should be represented as a rich text
string (see “Rich Text Strings” on page 680). If the field has a value, the RV
entry of the field dictionary (Table 8.71) specifies the rich text string.
692
CHAPTER 8
Interactive Features
The field’s text is held in a text string (or, beginning with PDF 1.5, a stream) in the
V (value) entry of the field dictionary. The contents of this text string or stream
are used to construct an appearance stream for displaying the field, as described
under “Variable Text” on page 677. The text is presented in a single style (font,
size, color, and so forth), as specified by the DA (default appearance) string.
If the FileSelect flag (PDF 1.4) is set, the field functions as a file-select control. In
this case, the field’s text represents the pathname of a file whose contents are to be
submitted as the field’s value:
• For fields submitted in HTML Form format, the submission uses the MIME
content type multipart / form-data, as described in Internet RFC 2045, Multi-
purpose Internet Mail Extensions (MIME), Part One: Format of Internet Message
Bodies (see the Bibliography).
• For Forms Data Format (FDF) submission, the value of the V entry in the FDF
field dictionary (see “FDF Fields” on page 717) is a file specification (Section
3.10, “File Specifications”) identifying the selected file.
• XML format is not supported for file-select controls; therefore, no value is sub-
mitted in this case.
Besides the usual entries common to all fields (see Table 8.69 on page 675) and to
fields containing variable text (see Table 8.71), the field dictionary for a text field
can contain the additional entry shown in Table 8.78.
TABLE 8.78 Additional entry specific to a text field
KEY
TYPE
VALUE
MaxLen
integer
(Optional; inheritable) The maximum length of the field’s text, in characters.
Example 8.18 shows the object definitions for a typical text field.
Example 8.18
6 0 obj
<< /FT /Tx
/Ff
…
% Set Multiline flag
/T ( Silly prose )
/DA ( 0 0 1 rg /Ti 12 Tf )
/V ( The quick brown fox ate the lazy mouse )
/AP << /N 5 0 R >>
>>
endobj
693
SECTION 8.6
Interactive Forms
5 0 obj
<< /Resources 21 0 R
/Length 172
>>
stream
/Tx BMC
q
BT
0 0 1 rg
/Ti
12 Tf
1 0 0 1 100 100 Tm
0 0 Td
( The quick brown fox ) Tj
0 −13 Td
( ate the lazy mouse. ) Tj
ET
Q
EMC
endstream
endobj
Choice Fields
A choice field (field type Ch) contains several text items, one or more of which
may be selected as the field value. The items may be presented to the user in
either of two forms:
• A scrollable list box
• A combo box consisting of a drop-down list optionally accompanied by an edit-
able text box in which the user can type a value other than the predefined
choices
TABLE 8.79 Field flags specific to choice fields
BIT POSITION
NAME
MEANING
18
Combo
If set, the field is a combo box; if clear, the field is a list box.
19
Edit
If set, the combo box includes an editable text box as well as a drop-
down list; if clear, it includes only a drop-down list. This flag is mean-
ingful only if the Combo flag is set.
694
CHAPTER 8
Interactive Features
BIT POSITION
NAME
MEANING
20
Sort
If set, the field’s option items should be sorted alphabetically. This flag
is intended for use by form authoring tools, not by PDF viewer appli-
cations. Viewers should simply display the options in the order in
which they occur in the Opt array (see Table 8.80).
22
MultiSelect
(PDF 1.4) If set, more than one of the field’s option items may be se-
lected simultaneously; if clear, no more than one item at a time may
be selected.
23
DoNotSpellCheck
(PDF 1.4) If set, text entered in the field is not spell-checked. This flag
is meaningful only if the Combo and Edit flags are both set.
27
CommitOnSelChange
(PDF 1.5) If set, the new value is committed as soon as a selection is
made with the pointing device. This option enables applications to
perform an action once a selection is made, without requiring the user
to exit the field. If clear, the new value is not committed until the user
exits the field.
The various types of choice fields are distinguished by flags in the Ff entry, as
shown in Table 8.79. Table 8.80 shows the field dictionary entries specific to
choice fields.
TABLE 8.80 Additional entries specific to a choice field
KEY
TYPE
VALUE
Opt
array
(Optional) An array of options to be presented to the user. Each element of the array is
either a text string representing one of the available options or an array consisting of two
text strings: the option’s export value and the text to be displayed as the name of the op-
tion (see implementation note 122 in Appendix H).
If this entry is not present, no choices should be presented to the user.
TI
integer
(Optional) For scrollable list boxes, the top index (the index in the Opt array of the first
option visible in the list). Default value: 0.
I
array
(Sometimes required, otherwise optional; PDF 1.4) For choice fields that allow multiple
selection (MultiSelect flag set), an array of integers, sorted in ascending order, represent-
ing the zero-based indices in the Opt array of the currently selected option items. This
entry is required when two or more elements in the Opt array have different names but
the same export value or when the value of the choice field is an array. In other cases, the
entry is permitted but not required. If the items identified by this entry differ from those
in the V entry of the field dictionary (see below), the V entry takes precedence.
695
SECTION 8.6
Interactive Forms
The Opt array specifies the list of options in the choice field, each of which is rep-
resented by a text string to be displayed on the screen. Each element of the Opt
array contains either this text string by itself or a two-element array, whose sec-
ond element is the text string and whose first element is a text string representing
the export value to be used when exporting interactive form field data from the
document.
The field dictionary’s V (value) entry (see Table 8.69 on page 675) identifies the
item or items currently selected in the choice field. If the field does not allow mul-
tiple selection—that is, if the MultiSelect flag (PDF 1.4) is not set—or if multiple
selection is supported but only one item is currently selected, V is a text string
representing the name of the selected item, as given in the field dictionary’s Opt
array. If multiple items are selected, V is an array of such strings. (For items repre-
sented in the Opt array by a two-element array, the name string is the second of
the two array elements.) The default value of V is null, indicating that no item is
currently selected.
Example 8.19 shows a typical choice field definition.
Example 8.19
<< /FT /Ch
/Ff
…
/T ( Body Color )
/V ( Blue )
/Opt
[
( Red )
( My favorite color )
( Blue )
]
>>
Signature Fields
A signature field (PDF 1.3) is a form field that contains a digital signature (see
Section 8.7, “Digital Signatures”). The field dictionary representing a signature
field may contain the additional entries listed in Table 8.81, as well as the stan-
dard entries described in Table 8.69. The field type (FT) is Sig, and the field value
(V) is a signature dictionary containing the signature and specifying various at-
tributes of the signature field (see Table 8.102).
696
CHAPTER 8
Interactive Features
Filling in (signing) the signature field entails updating at least the V entry and
usually also the AP entry of the associated widget annotation. Exporting a signa-
ture field typically exports the T, V, and AP entries.
Like any other field, a signature field may actually be described by a widget anno-
tation dictionary containing entries pertaining to an annotation as well as a field
(see “Widget Annotations” on page 640). The annotation rectangle (Rect) in such
a dictionary gives the position of the field on its page. Signature fields that are not
intended to be visible should have an annotation rectangle that has zero height
and width.
The appearance dictionary (AP) of a signature field’s widget annotation defines
the field’s visual appearance on the page
(see Section
8.4.4,
“Appearance
Streams”). Information about how Acrobat handles digital signature appearances
is in the technical note Digital Signature Appearances (see the Bibliography).
TABLE 8.81 Additional entries specific to a signature field
KEY
TYPE
VALUE
Lock
dictionary
(Optional; must be an indirect reference; PDF 1.5) A signature field lock dictionary that
specifies a set of form fields to be locked when this signature field is signed. Table 8.82
lists the entries in this dictionary.
SV
dictionary
(Optional; must be an indirect reference; PDF 1.5) A seed value dictionary (see Table
8.83) containing information that constrains the properties of a signature that is ap-
plied to this field.
The value of the SV entry in the field dictionary is a seed value dictionary whose
entries (see Table 8.83) provide constraining information that is to be used at the
time the signature is applied. Its Ff entry specifies whether the other entries in the
dictionary are required to be honored or whether they are merely recommenda-
tions.
Note: The seed value dictionary may include seed values for private entries belong-
ing to multiple handlers. A given handler should use only those entries that are per-
tinent to itself and ignore the others.
697
SECTION 8.6
Interactive Forms
TABLE 8.82 Entries in a signature field lock dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
SigFieldLock for a signature field lock dictionary.
Action
name
(Required) A name which, in conjunction with Fields, indicates the set of fields that
should be locked. Valid values are:
All
All fields in the document
Include
All fields specified in Fields
Exclude
All fields except those specified in Fields
Fields
array
(Required if the value of Action is Include or Exclude) An array of text strings containing
field names.
TABLE 8.83 Entries in a signature field seed value dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present,
must be SV for a seed value dictionary.
Filter
name
(Optional) The signature handler to be used to sign the signature field. Begin-
ning with PDF 1.7, if Filter is specified and the Ff entry indicates this entry is a
required constraint, then the signature handler specified by this entry must be
used when signing; otherwise, signing must not take place. If Ff indicates that
this is an optional constraint, this handler should be used if it is available. If it
is not available, a different handler can be used instead.
SubFilter
array
(Optional) An array of names indicating encodings to use when signing. The
first name in the array that matches an encoding supported by the signature
handler should be the encoding that is actually used for signing. If SubFilter is
specified and the Ff entry indicates that this entry is a required constraint, then
the first matching encodings must be used when signing; otherwise, signing
must not take place. If Ff indicates that this is an optional constraint, then the
first matching encoding should be used if it is available. If it is not available, a
different encoding can be used.
698
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
DigestMethod
array
(Optional; PDF 1.7) An array of names indicating acceptable digest algorithms
to use while signing. The valid values are SHA1, SHA256, SHA384, SHA512 and
RIPEMD160. The default value is implementation-specific.
Note: This property is only applicable if the digital credential signing contains
RSA public/private keys. If it contains DSA public/ private key, the digest algo-
rithm is always SHA1 and this attribute is ignored.
V
real
(Optional) The minimum required capability of the signature field seed value
dictionary parser. A value of 1 specifies that the parser must be able to recog-
nize all seed value dictionary entries specified in PDF 1.5. A value of 2 specifies
that it must be able to recognize all seed value dictionary entries specified in
PDF 1.7 and earlier.
The Ff entry indicates whether this is a required constraint.
Note: The PDF Reference fifth edition (PDF 1.6) and earlier, erroneously indi-
cates that the V entry is of type integer. This entry is of type real.
Cert
dictionary
(Optional) A certificate seed value dictionary (see Table 8.84) containing infor-
mation about the certificate to be used when signing.
Reasons
array
(Optional) An array of text strings that specifying possible reasons for signing
a document. If specified, the reasons supplied in this entry replace those used
by viewer applications. The Ff entry specifies whether one of the reasons in the
array must be used in the signature.
• If the Reasons array is provided and the Ff entry indicates that Reasons is a
required constraint, one of the reasons in the array must be used for the sig-
nature dictionary; otherwise, signing must not take place. If the Ff entry in-
dicates Reasons is an optional constraint, one of the reasons in the array can
be chosen or a custom reason can be provided.
• If the Reasons array is omitted or contains a single 0-character length string
and the Ff entry indicates that Reasons is a required constraint, the Reason
entry must be omitted from the signature dictionary (see Table 8.102).
MDP
dictionary
(Optional; PDF 1.6) A dictionary containing a single entry whose key is P and
whose value is an integer between 0 and 3. A value of 0 defines the signature as
an ordinary (non-author) signature (see Section 8.7, “Digital Signatures”). The
values 1 through 3 are used for author signatures and correspond to the value
of P in a DocMDP transform parameters dictionary (see Table 8.104).
If this entry is not present or does not contain a P entry, no rules are defined
regarding the type of signature or its permissions.
699
SECTION 8.6
Interactive Forms
KEY
TYPE
VALUE
TimeStamp
dictionary
(Optional; PDF 1.6) A time stamp dictionary containing two entries:
URL
An ASCII string specifying the URL of a time-stamping server,
providing a time stamp that is compliant with RFC 3161, Internet
X.509 Public Key Infrastructure Time-Stamp Protocol (see the Bib-
liography).
Ff
An integer whose value is 1 (the signature is required to have a
time stamp) or 0 (the signature is not required to have a time
stamp). Default value: 0.
LegalAttestation
array
(Optional; PDF 1.6) An array of text strings specifying possible legal attesta-
tions (see Section 8.7.4, “Legal Content Attestations”). The value of the corre-
sponding flag in the Ff entry indicates whether this is a required constraint.
AddRevInfo
boolean
(Optional; PDF 1.7) A flag indicating whether revocation checking should be
carried out. If AddRevInfo is true, the viewer application performs the follow-
ing additional tasks when signing the signature field:
• Perform revocation checking of the certificate (and the corresponding issu-
ing certificates) used to sign.
• Include the revocation information within the signature value.
A value of true is relevant only if SubFilter is adbe.pkcs7.detached or
adbe.pkcs7.sha1. If SubFilter is x509.rsa_sha1, this entry must be omitted or
set to false; otherwise, the signature process may fail.
If AddRevInfo is true and the Ff entry indicates this is a required constraint,
then the tasks described above must be performed. If they cannot be per-
formed, then signing must fail.
Default value: false
Ff
integer
(Optional) A set of bit flags specifying the interpretation of specific entries in
this dictionary. A value of 1 for the flag indicates that the associated entry is a
required constraint. A value of 0 indicates that the associated entry is an op-
tional constraint. Bit positions are 1 (Filter); 2 (SubFilter); 3 (V); 4 (Reasons); 5
(LegalAttestation); 6(AddRevInfo); and 7(DigestMethod). Default value: 0.
700
CHAPTER 8
Interactive Features
TABLE 8.84 Entries in a certificate seed value dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present,
must be SVCert for a certificate seed value dictionary.
Subject
array
(Optional) An array of byte strings containing DER-encoded X.509v3 certifi-
cates that are acceptable for signing. X.509v3 certificates are described in RFC
3280, Internet X.509 Public Key Infrastructure, Certificate and Certificate Revo-
cation List (CRL) Profile (see the Bibliography). The value of the corresponding
flag in the Ff entry indicates whether this is a required constraint.
SubjectDN
array of
(Optional; PDF 1.7) An array of dictionaries, where each dictionary contains
dictionaries
key value pairs, that specify the Subject Distinguished Name (DN) that must
be present within the certificate for it to be acceptable for signing. The certifi-
cate must at a minimum contain all the attributes specified in the dictionary.
That is, the certificate can contain additional attributes. The Subject Distin-
guished Name is described in RFC 3280 (see the Bibliography). The key can be
any legal attribute identifier. Attribute names are typically of the form ‘cn’, ‘o’,
‘email’, ‘2.5.4.43’ and always contain characters in the set a-z, A-Z, 0-9 and ‘.’.
Values are text strings. An example dictionary is
<</cn (John Smith) /1.5.4.43 (JS)>>.
The value of the corresponding flag in the Ff entry indicates whether this entry
is a required constraint.
701
SECTION 8.6
Interactive Forms
KEY
TYPE
VALUE
KeyUsage
array of
(Optional; PDF 1.7) An array of ASCII strings, where each string specifies an
ASCII
acceptable key-usage extension that must be present in the signing certificate.
strings
Multiple strings specify a range of acceptable key-usage extensions. The key-
usage extension is described in RFC 3280 (see the Bibliography).
Each character in a string represents a key-usage type, where the order of the
characters indicates the key-usage extension it represents. The first through
ninth characters in the array, from left to right, represent the required value for
the following key-usage extensions:
1
digitalSignature
4
dataEncipherment 7
cRLSign
2
non-Repudiation
5
keyAgreement
8
encipherOnly
3
keyEncipherment
6
keyCertSign
9
decipherOnly
Any additional characters are ignored. Any missing characters or characters
that are not one of the following values, should be set to ‘X’. The following
character values are supported:
0
Corresponding key-usage must not be set.
1
Corresponding key-usage must be set.
X
State of the corresponding key-usage does not matter.
For example, the string values ‘1’ and ‘1XXXXXXXX’ represent settings where the
key-usage type digitalSignature must be set and the state of all other key-usage
types do not matter.
The value of the corresponding flag in the Ff entry indicates whether this is a
required constraint.
Issuer
array
(Optional) An array of byte strings containing DER-encoded X.509v3 certifi-
cates of acceptable issuers. If the signer’s certificate chains up to any of the
specified issuers (either directly or indirectly), the certificate is considered ac-
ceptable for signing. The value of the corresponding flag in the Ff entry indi-
cates whether this is a required constraint.
OID
array
(Optional) An array of byte strings that contain Object Identifiers (OIDs) of
the certificate policies that must be present in the signing certificate. An exam-
ple of such a string is (2.16.840.1.113733.1.7.1.1). This field is only applicable if
the value of Issuer is not empty. The certificate policies extension is described
in RFC 3280 (see the Bibliography). The value of the corresponding flag in the
Ff entry indicates whether this is a required constraint.
702
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
URL
ASCII
(Optional) A URL, the use for which is defined by the URLType entry.
string
URLType
Name
(Optional; PDF 1.7) A name indicating the usage of the URL entry. There are
standard uses and there can be implementation-specific uses for this URL. The
following value specifies a valid standard usage:
Browser - The URL references content that should be displayed in a web
browser to allow enrolling for a new credential if a matching credential
is not found. The Ff attribute’s URL bit is ignored for this usage.
The following value specifies a valid implementation-specific usage, defined
for use by Adobe Systems:
ASSP - The URL references a signature web service that can be used for
server-based signing. If the Ff attribute’s URL bit indicates that this is a
required constraint, this implies that the credential used when signing
must come from this server.
Third parties can extend the use of this attribute with their own attribute val-
ues, which must conform to the guidelines described in Appendix E.
The default value is Browser.
Ff
integer
(Optional) A set of bit flags specifying the interpretation of specific entries in
this dictionary. A value of 1 for the flag means that a signer is required to use
only the specified values for the entry. A value of 0 means that other values are
permissible. Bit positions are 1 (Subject); 2 (Issuer); 3 (OID); 4 (SubjectDN);
5 (Reserved); 6 (KeyUsage); 7 (URL).
Default value: 0.
8.6.4
Form Actions
Interactive forms support four special types of actions in addition to those de-
scribed in Section 8.5.3, “Action Types”:
• Submit-form actions transmit the names and values of selected interactive form
fields to a specified uniform resource locator (URL), presumably the address of
a Web server that will process them and send back a response.
• Reset-form actions reset selected interactive form fields to their default values.
• Import-data actions import Forms Data Format (FDF) data into the document’s
interactive form from a specified file.
703
SECTION 8.6
Interactive Forms
• JavaScript actions (PDF 1.3) cause a script to be compiled and executed by the
JavaScript interpreter.
Submit-Form Actions
A submit-form action transmits the names and values of selected interactive form
fields to a specified uniform resource locator (URL), presumably the address of a
Web server that will process them and send back a response. Table 8.85 shows the
action dictionary entries specific to this type of action.
The value of the action dictionary’s Flags entry is an unsigned 32-bit integer con-
taining flags specifying various characteristics of the action. Bit positions within
the flag word are numbered from 1 (low-order) to 32 (high-order). Table 8.86
shows the meanings of the flags; all undefined flag bits are reserved and must be
set to 0.
TABLE 8.85 Additional entries specific to a submit-form action
KEY
TYPE
VALUE
S
name
(Required) The type of action that this dictionary describes; must be
SubmitForm for a submit-form action.
F
file specification
(Required) A URL file specification (see Section 3.10.4, “URL Spec-
ifications”) giving the uniform resource locator (URL) of the script
at the Web server that will process the submission.
Fields
array
(Optional) An array identifying which fields to include in the sub-
mission or which to exclude, depending on the setting of the
Include/Exclude flag in the Flags entry (see Table 8.86). Each ele-
ment of the array is either an indirect reference to a field dictionary
or (PDF 1.3) a text string representing the fully qualified name of a
field. Elements of both kinds may be mixed in the same array.
If this entry is omitted, the Include/Exclude flag is ignored, and all
fields in the document’s interactive form are submitted except those
whose NoExport flag (see Table 8.70 on page 676) is set. (Fields
with no values may also be excluded, depending on the setting of
the IncludeNoValueFields flag; see Table 8.86.) See the text follow-
ing Table 8.86 for further discussion.
Flags
integer
(Optional; inheritable) A set of flags specifying various characteris-
tics of the action (see Table 8.86). Default value: 0.
704
CHAPTER 8
Interactive Features
TABLE 8.86 Flags for submit-form actions
BIT POSITION
NAME
MEANING
1
Include/Exclude
If clear, the Fields array (see Table 8.85) specifies which fields to
include in the submission. (All descendants of the specified fields in
the field hierarchy are submitted as well.)
If set, the Fields array tells which fields to exclude. All fields in the
document’s interactive form are submitted except those listed in the
Fields array and those whose NoExport flag (see Table 8.70 on page
676) is set.
2
IncludeNoValueFields
If set, all fields designated by the Fields array and the Include/
Exclude flag are submitted, regardless of whether they have a value
(V entry in the field dictionary). For fields without a value, only the
field name is transmitted.
If clear, fields without a value are not submitted.
3
ExportFormat
Meaningful only if the SubmitPDF and XFDF flags are clear. If set,
field names and values are submitted in HTML Form format. If
clear, they are submitted in Forms Data Format (FDF); see Section
8.6.6, “Forms Data Format.”
4
GetMethod
If set, field names and values are submitted using an HTTP GET
request. If clear, they are submitted using a POST request. This flag
is meaningful only when the ExportFormat flag is set; if ExportFor-
mat is clear, this flag must also be clear.
5
SubmitCoordinates
If set, the coordinates of the mouse click that caused the submit-
form action are transmitted as part of the form data. The coordinate
values are relative to the upper-left corner of the field’s widget an-
notation rectangle. They are represented in the data in the format
name . x = xval & name . y = yval
where name is the field’s mapping name (TM in the field dictionary)
if present; otherwise, name is the field name. If the value of the TM
entry is a single space character, both the name and the dot follow-
ing it are suppressed, resulting in the format
x = xval & y = yval
This flag is meaningful only when the ExportFormat flag is set. If
ExportFormat is clear, this flag must also be clear.
705
SECTION 8.6
Interactive Forms
BIT POSITION
NAME
MEANING
6
XFDF
(PDF 1.4) Meaningful only if the SubmitPDF flags are clear. If set,
field names and values are submitted as XFDF.
7
IncludeAppendSaves
(PDF 1.4) Meaningful only when the form is being submitted in
Forms Data Format (that is, when both the XFDF and ExportFor-
mat flags are clear). If set, the submitted FDF file includes the con-
tents of all incremental updates to the underlying PDF document,
as contained in the Differences entry in the FDF dictionary (see
Table 8.93 on page 714). If clear, the incremental updates are not in-
cluded.
8
IncludeAnnotations
(PDF 1.4) Meaningful only when the form is being submitted in
Forms Data Format (that is, when both the XFDF and ExportFor-
mat flags are clear). If set, the submitted FDF file includes all mark-
up annotations in the underlying PDF document (see “Markup
Annotations” on page 616). If clear, markup annotations are not in-
cluded.
9
SubmitPDF
(PDF 1.4) If set, the document is submitted as PDF, using the
MIME content type application / pdf (described in Internet RFC
2045, Multipurpose Internet Mail Extensions (MIME), Part One:
Format of Internet Message Bodies; see the Bibliography). If set, all
other flags are ignored except GetMethod.
10
CanonicalFormat
(PDF 1.4) If set, any submitted field values representing dates are
converted to the standard format described in Section
3.8.3,
“Dates.” (The interpretation of a form field as a date is not specified
explicitly in the field itself but only in the JavaScript code that pro-
cesses it.)
11
ExclNonUserAnnots
(PDF 1.4) Meaningful only when the form is being submitted in
Forms Data Format
(that is, when both the XFDF and
ExportFormat flags are clear) and the IncludeAnnotations flag is
set. If set, it includes only those markup annotations whose T entry
(see Table 8.21) matches the name of the current user, as deter-
mined by the remote server to which the form is being submitted.
(The T entry for markup annotations specifies the text label to be
displayed in the title bar of the annotation’s pop-up window and is
assumed to represent the name of the user authoring the annota-
tion.) This allows multiple users to collaborate in annotating a sin-
gle remote PDF document without affecting one another’s
annotations.
706
CHAPTER 8
Interactive Features
BIT POSITION
NAME
MEANING
12
ExclFKey
(PDF 1.4) Meaningful only when the form is being submitted in
Forms Data Format (that is, when both the XFDF and ExportFor-
mat flags are clear). If set, the submitted FDF excludes the F entry.
14
EmbedForm
(PDF 1.5) Meaningful only when the form is being submitted in
Forms Data Format (that is, when both the XFDF and ExportFor-
mat flags are clear). If set, the F entry of the submitted FDF is a file
specification containing an embedded file stream representing the
PDF file from which the FDF is being submitted.
The set of fields whose names and values are to be submitted is defined by the
Fields array in the action dictionary (Table 8.85) together with the Include/
Exclude and IncludeNoValueFields flags in the Flags entry (Table 8.86). Each ele-
ment of the Fields array identifies an interactive form field, either by an indirect
reference to its field dictionary or (PDF 1.3) by its fully qualified field name (see
“Field Names” on page 676). If the Include/Exclude flag is clear, the submission
consists of all fields listed in the Fields array, along with any descendants of those
fields in the field hierarchy. If the Include/Exclude flag is set, the submission con-
sists of all fields in the document’s interactive form except those listed in the
Fields array.
Note: The NoExport flag in the field dictionary’s Ff entry (see Table 8.69 on page
675 and Table 8.70 on page 676) takes precedence over the action’s Fields array and
Include/Exclude flag. Fields whose NoExport flag is set are never included in a
submit-form action.
Field names and values may be submitted in any of the following formats, de-
pending on the settings of the action’s ExportFormat, SubmitPDF, and XFDF
flags (see the Bibliography for references):
• HTML Form format (described in the HTML 4.01 Specification)
• Forms Data Format (FDF), which is described in Section 8.6.6, “Forms Data
Format”; see also implementation note 123 in Appendix H.
• XFDF, a version of FDF based on XML. XFDF is described in the Adobe tech-
nical note XML Forms Data Format Specification, Version 2.0. XML is described
in the W3C document Extensible Markup Language (XML) 1.1)
• PDF (in this case, the entire document is submitted rather than individual
fields and values).
707
SECTION 8.6
Interactive Forms
The name submitted for each field is its fully qualified name (see “Field Names”
on page 676), and the value is specified by the V entry in its field dictionary.
Note: For pushbutton fields submitted in FDF, the value submitted is that of the AP
entry in the field’s widget annotation dictionary. If the submit-form action dictio-
nary contains no Fields entry, such pushbutton fields are not submitted at all.
Fields with no value (that is, whose field dictionary does not contain a V entry)
are ordinarily not included in the submission. The submit-form action’s Include-
NoValueFields flag can override this behavior. If this flag is set, such valueless
fields are included in the submission by name only, with no associated value.
Reset-Form Actions
A reset-form action resets selected interactive form fields to their default values;
that is, it sets the value of the V entry in the field dictionary to that of the DV entry
(see Table 8.69 on page 675). If no default value is defined for a field, its V entry is
removed. For fields that can have no value (such as pushbuttons), the action has
no effect. Table 8.87 shows the action dictionary entries specific to this type of
action.
The value of the action dictionary’s Flags entry is an unsigned 32-bit integer con-
taining flags specifying various characteristics of the action. Bit positions within
the flag word are numbered from 1 (low-order) to 32 (high-order). At the time of
publication, only one flag is defined for this type of action; Table 8.88 shows its
meaning. All undefined flag bits are reserved and must be set to 0.
TABLE 8.87 Additional entries specific to a reset-form action
KEY
TYPE
VALUE
S
name
(Required) The type of action that this dictionary describes; must be
ResetForm for a reset-form action.
708
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
Fields
array
(Optional) An array identifying which fields to reset or which to exclude
from resetting, depending on the setting of the Include/Exclude flag in
the Flags entry (see Table 8.88). Each element of the array is either an in-
direct reference to a field dictionary or (PDF 1.3) a text string represent-
ing the fully qualified name of a field. Elements of both kinds may be
mixed in the same array.
If this entry is omitted, the Include/Exclude flag is ignored; all fields in
the document’s interactive form are reset.
Flags
integer
(Optional; inheritable) A set of flags specifying various characteristics of
the action (see Table 8.88). Default value: 0.
TABLE 8.88 Flag for reset-form actions
BIT POSITION
NAME
MEANING
1
Include/Exclude
If clear, the Fields array (see Table 8.87) specifies which fields to reset.
(All descendants of the specified fields in the field hierarchy are reset as
well.) If set, the Fields array indicates which fields to exclude from reset-
ting; that is, all fields in the document’s interactive form are reset except
those listed in the Fields array.
Import-Data Actions
An import-data action imports Forms Data Format (FDF) data into the docu-
ment’s interactive form from a specified file (see Section 8.6.6, “Forms Data For-
mat”). Table 8.89 shows the action dictionary entries specific to this type of action.
TABLE 8.89 Additional entries specific to an import-data action
KEY
TYPE
VALUE
S
name
(Required) The type of action that this dictionary describes; must be ImportData
for an import-data action.
F
file specification
(Required) The FDF file from which to import the data. (See implementation
notes 124 and 125 in Appendix H.)
709
SECTION 8.6
Interactive Forms
JavaScript Actions
A JavaScript action (PDF 1.3) causes a script to be compiled and executed by the
JavaScript interpreter. Depending on the nature of the script, various interactive
form fields in the document may update their values or change their visual ap-
pearances. Netscape Communications Corporation’s Client-Side JavaScript Refer-
ence and the Adobe JavaScript for Acrobat API Reference (see the Bibliography)
give details on the contents and effects of JavaScript scripts. Table 8.90 shows the
action dictionary entries specific to this type of action.
TABLE 8.90 Additional entries specific to a JavaScript action
KEY
TYPE
VALUE
S
name
(Required) The type of action that this dictionary describes; must be JavaScript
for a JavaScript action.
JS
text string or
(Required) A text string or text stream containing the JavaScript script to be exe-
text stream
cuted.
Note: PDFDocEncoding or Unicode encoding (the latter identified by the Unicode
prefix U+ FEFF) is used to encode the contents of the string or stream. (See imple-
mentation note 126 in Appendix H.)
To support the use of parameterized function calls in JavaScript scripts, the
JavaScript entry in a PDF document’s name dictionary (see Section 3.6.3, “Name
Dictionary”) can contain a name tree that maps name strings to document-level
JavaScript actions. When the document is opened, all of the actions in this name
tree are executed, defining JavaScript functions for use by other scripts in the
document.
Note: The name strings associated with individual JavaScript actions in the name
dictionary serve merely as a convenient means for organizing and packaging scripts.
The names are arbitrary and need not bear any relation to the JavaScript name
space.
710
CHAPTER 8
Interactive Features
8.6.5
Named Pages
The optional Pages entry (PDF 1.3) in a document’s name dictionary (see Section
3.6.3, “Name Dictionary”) contains a name tree that maps name strings to indi-
vidual pages within the document. Naming a page allows it to be referenced in
two different ways:
• An import-data action can add the named page to the document into which
FDF is being imported, either as a page or as a button appearance.
• A script executed by a JavaScript action can add the named page to the current
document as a regular page.
A named page that is to be visible to the user should be left in the page tree (see
Section 3.6.2, “Page Tree”), and there should be a reference to it in the appropriate
leaf node of the name dictionary’s Pages tree. If the page is not to be displayed by
the viewer application, it should be referenced from the name dictionary’s
Templates tree instead. Such invisible pages should have an object type of
Template rather than Page and should have no Parent or B entry (see Table 3.27
on page 145). Regardless of whether the page is named in the Pages or Templates
tree or is added to a document by an import-data or JavaScript action, the new
copy is not itself named.
8.6.6
Forms Data Format
This section describes Forms Data Format (FDF), the file format used for inter-
active form data (PDF 1.2). FDF is used when submitting form data to a server,
receiving the response, and incorporating it into the interactive form. It can also
be used to export form data to stand-alone files that can be stored, transmitted
electronically, and imported back into the corresponding PDF interactive form.
In addition, beginning in PDF 1.3, FDF can be used to define a container for an-
notations that are separate from the PDF document to which they apply.
711
SECTION 8.6
Interactive Forms
FDF is based on PDF; it uses the same syntax (see Section 3.1, “Lexical Conven-
tions”) and basic object types (Section 3.2, “Objects”), and has essentially the
same file structure (Section 3.4, “File Structure”). However, it differs from PDF in
the following ways:
• The cross-reference table (Section 3.4.3, “Cross-Reference Table”) is optional.
• FDF files cannot be updated (see Section 3.4.5, “Incremental Updates”). Ob-
jects can only be of generation 0, and no two objects can have the same object
number.
• The document structure is much simpler than PDF, since the body of an FDF
document consists of only one required object.
• The length of a stream may not be specified by an indirect object.
FDF uses the MIME content type application / vnd . fdf. On the Windows and
UNIX platforms, FDF files have the extension . fdf; on Mac OS, they have file type
'FDF '.
FDF File Structure
An FDF file is structured in essentially the same way as a PDF file but contains
only those elements required for the export and import of interactive form and
annotation data. It consists of three required elements and one optional element
(see Figure 8.10):
• A one-line header identifying the version number of the PDF specification to
which the file conforms
• A body containing the objects that make up the content of the file
• An optional cross-reference table containing information about the objects in
the file
• A trailer giving the location of various objects within the body of the file
712
CHAPTER 8
Interactive Features
Header
Body
Cross-reference
table (optional)
Trailer
FIGURE 8.10 FDF file structure
FDF Header
The first line of an FDF file is a header, originally intended to identify the version
of the PDF specification to which the file conforms. However, for historical rea-
sons, this version number is now frozen and must read
%FDF−1 . 2
The true version number is now given by the Version entry in the FDF catalog
dictionary (see “FDF Catalog,” below; see also implementation note 127 in Ap-
pendix H).
FDF Body
The body of an FDF file consists of a sequence of indirect objects representing the
file’s catalog (see “FDF Catalog” on page 713) together with any additional objects
that the catalog may reference. The objects are of the same basic types described
in Section 3.2, “Objects.” Just as in PDF, objects in FDF can be direct or indirect.
713
SECTION 8.6
Interactive Forms
FDF Trailer
The trailer of an FDF file enables an application reading the file to find significant
objects quickly within the body of the file. The last line of the file contains only
the end-of-file marker, %%EOF. This marker is preceded by the FDF trailer dictio-
nary, consisting of the keyword trailer followed by a series of one or more key-
value pairs enclosed in double angle brackets (<<… >>). The only required key is
Root, whose value is an indirect reference to the file’s catalog dictionary (see Table
8.91). The trailer may optionally contain additional entries for objects that are
referenced from within the catalog.
TABLE 8.91 Entry in the FDF trailer dictionary
KEY
TYPE
VALUE
Root
dictionary
(Required; must be an indirect reference) The catalog object for this FDF file (see
“FDF Catalog,” below).
Thus, the trailer has the overall structure
trailer
<< /Root c 0 R
key2 value2
…
keyn valuen
>>
%%EOF
where c is the object number of the file’s catalog dictionary.
FDF Catalog
The root node of an FDF file’s object hierarchy is the catalog dictionary, located
by means of the Root entry in the file’s trailer dictionary (see “FDF Trailer,”
above). As shown in Table 8.92, the only required entry in the catalog is FDF; its
value is an FDF dictionary (Table 8.93), which in turn contains references to other
objects describing the file’s contents. The catalog may also contain an optional
Version entry identifying the version of the PDF specification to which this FDF
file conforms.
714
CHAPTER 8
Interactive Features
TABLE 8.92 Entries in the FDF catalog dictionary
KEY
TYPE
VALUE
Version
name
(Optional; PDF 1.4) The version of the PDF specification to which
this FDF file conforms (for example, 1.4) if later than the version
specified in the file’s header (see “FDF Header” on page 712). If the
header specifies a later version, or if this entry is absent, the docu-
ment conforms to the version specified in the header.
Note: The value of this entry is a name object, not a number, and
therefore must be preceded by a slash character (/) when written in
the FDF file (for example, /1.4).
FDF
dictionary
(Required) The FDF dictionary for this file (see Table 8.93).
Sig
dictionary
(Optional; PDF 1.5) A signature dictionary indicating that the doc-
ument is signed using an object digest (see Section 8.7, “Digital Sig-
natures”). This dictionary must contain a signature reference
dictionary whose Data entry is an indirect reference to the catalog
and whose TransformMethod entry is Identity.
TABLE 8.93 Entries in the FDF dictionary
KEY
TYPE
VALUE
F
file specification
(Optional) The source file or target file: the PDF document file that
this FDF file was exported from or is intended to be imported into.
ID
array
(Optional) An array of two byte strings constituting a file identifier
(see Section 10.3, “File Identifiers”) for the source or target file des-
ignated by F, taken from the ID entry in the file’s trailer dictionary
(see Section 3.4.4, “File Trailer”).
Fields
array
(Optional) An array of FDF field dictionaries (see “FDF Fields” on
page 717) describing the root fields (those with no ancestors in the
field hierarchy) to be exported or imported. This entry and the
Pages entry may not both be present.
Status
PDFDocEncoded
(Optional) A status string to be displayed indicating the result of an
string
action, typically a submit-form action (see “Submit-Form Actions”
on page 703). The string is encoded with PDFDocEncoding. (See
implementation note 128 in Appendix H.) This entry and the Pages
entry may not both be present.
715
SECTION 8.6
Interactive Forms
KEY
TYPE
VALUE
Pages
array
(Optional; PDF 1.3) An array of FDF page dictionaries (see “FDF
Pages” on page 720) describing new pages to be added to a PDF
target document. The Fields and Status entries may not be present
together with this entry.
Encoding
name
(Optional; PDF 1.3) The encoding to be used for any FDF field
value or option (V or Opt in the field dictionary; see Table 8.96 on
page 717) or field name that is a string and does not begin with the
Unicode prefix U+FEFF. (See implementation note 129 in Appendix
H.) Default value: PDFDocEncoding.
Annots
array
(Optional; PDF 1.3) An array of FDF annotation dictionaries (see
“FDF Annotation Dictionaries” on page 722). The array can include
annotations of any of the standard types listed in Table 8.20 on page
615 except Link, Movie, Widget, PrinterMark, Screen, and TrapNet.
Differences
stream
(Optional; PDF 1.4) A stream containing all the bytes in all incre-
mental updates made to the underlying PDF document since it was
opened (see Section 3.4.5, “Incremental Updates”). If a submit-
form action submitting the document to a remote server as FDF has
its IncludeAppendSaves flag set (see “Submit-Form Actions” on
page 703), the contents of this stream are included in the submis-
sion. This allows any digital signatures (see Section 8.7, “Digital
Signatures) to be transmitted to the server. An incremental update
is automatically performed just before the submission takes place,
in order to capture all changes made to the document. Note that the
submission always includes the full set of incremental updates back
to the time the document was first opened, even if some of them
may already have been included in intervening submissions.
Note: Although a Fields or Annots entry (or both) may be present
along with Differences, there is no guarantee that their contents will
be consistent with it. In particular, if Differences contains a digital sig-
nature, only the values of the form fields given in the Differences
stream can be considered trustworthy under that signature.
Target
string
(Optional; PDF 1.4) The name of a browser frame in which the un-
derlying PDF document is to be opened. This mimics the behavior
of the target attribute in HTML < href > tags.
EmbeddedFDFs
array
(Optional; PDF 1.4) An array of file specifications (see Section 3.10,
“File Specifications”) representing other FDF files embedded with-
in this one (Section 3.10.3, “Embedded File Streams”).
716
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
JavaScript
dictionary
(Optional; PDF 1.4) A JavaScript dictionary (see Table 8.95) defin-
ing document-level JavaScript scripts.
Embedded FDF files specified in the FDF dictionary’s EmbeddedFDFs entry may
optionally be encrypted. Besides the usual entries for an embedded file stream,
the stream dictionary representing such an encrypted FDF file must contain the
additional entry shown in Table 8.94 to identify the revision number of the FDF
encryption algorithm used to encrypt the file. Although the FDF encryption
mechanism is separate from the one for PDF file encryption described in Section
3.5, “Encryption,” revision 1 (the only one defined at the time of publication) uses
a similar RC4 encryption algorithm based on a 40-bit encryption key. The key is
computed by means of an MD5 hash, using a padded user-supplied password as
input. The computation is identical to steps 1 and 2 of Algorithm 3.2 on page 125;
the first 5 bytes of the result are the encryption key for the embedded FDF file.
TABLE 8.94 Additional entry in an embedded file stream dictionary for an encrypted
FDF file
KEY
TYPE
VALUE
EncryptionRevision
integer
(Required if the FDF file is encrypted; PDF 1.4) The revision number of the
FDF encryption algorithm used to encrypt the file. The only valid value
defined at the time of publication is 1.
The JavaScript entry in the FDF dictionary holds a JavaScript dictionary contain-
ing JavaScript scripts that are defined globally at the document level, rather than
associated with individual fields. The dictionary can contain scripts defining Jav-
aScript functions for use by other scripts in the document, as well as scripts to be
executed immediately before and after the FDF file is imported. Table 8.95 shows
the contents of this dictionary.
TABLE 8.95 Entries in the JavaScript dictionary
KEY
TYPE
VALUE
Before
text string or
(Optional) A text string or text stream containing a JavaScript script to be
text stream
executed just before the FDF file is imported.
After
text string or
(Optional) A text string or text stream containing a JavaScript script to be
text stream
executed just after the FDF file is imported.
717
SECTION 8.6
Interactive Forms
KEY
TYPE
VALUE
AfterPermsReady text string or
(Optional; PDF 1.6) A text string or text stream containing a JavaScript
text stream
script to be executed after the FDF file is imported and the usage rights in
the PDF document have been determined (see “UR” on page 733).
Note: Verification of usage rights requires the entire file to be present, in
which case this script defers execution until that requirement is met.
Doc
array
(Optional) An array defining additional JavaScript scripts to be added to
those defined in the JavaScript entry of the document’s name dictionary
(see Section 3.6.3, “Name Dictionary”). The array contains an even num-
ber of elements, organized in pairs. The first element of each pair is a
name and the second is a text string or text stream defining the script cor-
responding to that name. Each of the defined scripts is added to those al-
ready defined in the name dictionary and then executed before the script
defined in the Before entry is executed. As described in “JavaScript Ac-
tions” on page 709, these scripts are used to define JavaScript functions
for use by other scripts in the document.
FDF Fields
Each field in an FDF file is described by an FDF field dictionary. Table 8.96 shows
the contents of this type of dictionary. Most of the entries have the same form and
meaning as the corresponding entries in a field dictionary (Table 8.69 on page
675, Table 8.71 on page 678, Table 8.78 on page 692, and Table 8.80 on page 694)
or a widget annotation dictionary (Table 8.15 on page 606 and Table 8.39 on page
641). Unless otherwise indicated in the table, importing a field causes the values
of the entries in the FDF field dictionary to replace those of the corresponding
entries in the field with the same fully qualified name in the target document.
(See implementation notes 130-135 in Appendix H.)
TABLE 8.96 Entries in an FDF field dictionary
KEY
TYPE
VALUE
Kids
array
(Optional) An array containing the immediate children of this field.
Note: Unlike the children of fields in a PDF file, which must be specified as indirect object
references, those of an FDF field may be either direct or indirect objects.
T
text string
(Required) The partial field name (see “Field Names” on page 676).
V
(various)
(Optional) The field’s value, whose format varies depending on the field type; see the
descriptions of individual field types in Section 8.6.3 for further information.
718
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
Ff
integer
(Optional) A set of flags specifying various characteristics of the field (see Table 8.70
on page 676, Table 8.75 on page 686, Table 8.77 on page 691, and Table 8.79 on page
693). When imported into an interactive form, the value of this entry replaces that of
the Ff entry in the form’s corresponding field dictionary. If this field is present, the Set-
Ff and ClrFf entries, if any, are ignored.
SetFf
integer
(Optional) A set of flags to be set (turned on) in the Ff entry of the form’s cor-
responding field dictionary. Bits equal to 1 in SetFf cause the corresponding bits in Ff
to be set to 1. This entry is ignored if an Ff entry is present in the FDF field dictionary.
ClrFf
integer
(Optional) A set of flags to be cleared (turned off) in the Ff entry of the form’s corre-
sponding field dictionary. Bits equal to 1 in ClrFf cause the corresponding bits in Ff to
be set to 0. If a SetFf entry is also present in the FDF field dictionary, it is applied be-
fore this entry. This entry is ignored if an Ff entry is present in the FDF field dictio-
nary.
F
integer
(Optional) A set of flags specifying various characteristics of the field’s widget annota-
tion (see Section 8.4.2, “Annotation Flags”). When imported into an interactive form,
the value of this entry replaces that of the F entry in the form’s corresponding annota-
tion dictionary. If this field is present, the SetF and ClrF entries, if any, are ignored.
SetF
integer
(Optional) A set of flags to be set (turned on) in the F entry of the form’s correspond-
ing widget annotation dictionary. Bits equal to 1 in SetF cause the corresponding bits
in F to be set to 1. This entry is ignored if an F entry is present in the FDF field dictio-
nary.
ClrF
integer
(Optional) A set of flags to be cleared (turned off) in the F entry of the form’s corre-
sponding widget annotation dictionary. Bits equal to 1 in ClrF cause the correspond-
ing bits in F to be set to 0. If a SetF entry is also present in the FDF field dictionary, it
is applied before this entry. This entry is ignored if an F entry is present in the FDF
field dictionary.
AP
dictionary
(Optional) An appearance dictionary specifying the appearance of a pushbutton field
(see “Pushbuttons” on page 686). The appearance dictionary’s contents are as shown
in Table 8.19 on page 614, except that the values of the N, R, and D entries must all be
streams.
APRef
dictionary
(Optional; PDF 1.3) A dictionary holding references to external PDF files containing
the pages to use for the appearances of a pushbutton field. This dictionary is similar to
an appearance dictionary (see Table 8.19 on page 614), except that the values of the N,
R, and D entries must all be named page reference dictionaries (Table 8.100 on page
721). This entry is ignored if an AP entry is present.
719
SECTION 8.6
Interactive Forms
KEY
TYPE
VALUE
IF
dictionary
(Optional; PDF 1.3; button fields only) An icon fit dictionary (see Table 8.97) specify-
ing how to display a button field’s icon within the annotation rectangle of its widget
annotation.
Opt
array
(Required; choice fields only) An array of options to be presented to the user. Each
element of the array can take either of two forms:
• A text string representing one of the available options
• A two-element array consisting of a text string representing one of the available op-
tions and a default appearance string for constructing the item’s appearance dynam-
ically at viewing time (see “Variable Text” on page 677)
A
dictionary
(Optional) An action to be performed when this field’s widget annotation is activated
(see Section 8.5, “Actions”).
AA
dictionary
(Optional) An additional-actions dictionary defining the field’s behavior in response
to various trigger events (see Section 8.5.2, “Trigger Events”).
RV
text string or
(Optional; PDF 1.5) A rich text string, as described in “Rich Text Strings” on page 680.
text stream
In an FDF field dictionary representing a button field, the optional IF entry holds
an icon fit dictionary (PDF 1.3) specifying how to display the button’s icon within
the annotation rectangle of its widget annotation. Table 8.97 shows the contents
of this type of dictionary.
TABLE 8.97 Entries in an icon fit dictionary
KEY
TYPE
VALUE
SW
name
(Optional) The circumstances under which the icon should be scaled inside the annota-
tion rectangle:
A Always scale.
B Scale only when the icon is bigger than the annotation rectangle.
S Scale only when the icon is smaller than the annotation rectangle.
N Never scale.
Default value: A.
720
CHAPTER 8
Interactive Features
KEY
TYPE
VALUE
S
name
(Optional) The type of scaling to use:
A Anamorphic scaling: Scale the icon to fill the annotation rectangle exactly, with-
out regard to its original aspect ratio (ratio of width to height).
P Proportional scaling: Scale the icon to fit the width or height of the annotation
rectangle while maintaining the icon’s original aspect ratio. If the required hori-
zontal and vertical scaling factors are different, use the smaller of the two, cen-
tering the icon within the annotation rectangle in the other dimension.
Default value: P.
A
array
(Optional) An array of two numbers between 0.0 and 1.0 indicating the fraction of 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 of the annotation rectangle. A value of [ 0.5 0.5 ] centers it
within the rectangle. This entry is used only if the icon is scaled proportionally. Default
value: [ 0.5
0.5 ].
FB
boolean
(Optional; PDF 1.5) If true, indicates that the button appearance should be scaled to fit
fully within the bounds of the annotation without taking into consideration the line
width of the border; see implementation note 136 in Appendix H. Default value: false.
FDF Pages
The optional Pages field in an FDF dictionary (see Table 8.93 on page 714)
contains an array of FDF page dictionaries (PDF 1.3) describing new pages to be
added to the target document. Table 8.98 shows the contents of this type of
dictionary.
TABLE 8.98 Entries in an FDF page dictionary
KEY
TYPE
VALUE
Templates
array
(Required) An array of FDF template dictionaries (see Table 8.99) describing the
named pages that serve as templates on the page.
Info
dictionary
(Optional) An FDF page information dictionary containing additional informa-
tion about the page. At the time of publication, no entries have been defined for
this dictionary.
721
SECTION 8.6
Interactive Forms
An FDF template dictionary contains information describing a named page that
serves as a template. Table 8.99 shows the contents of this type of dictionary.
TABLE 8.99 Entries in an FDF template dictionary
KEY
TYPE
VALUE
TRef
dictionary
(Required) A named page reference dictionary (see Table 8.100) specifying the
location of the template.
Fields
array
(Optional) An array of references to FDF field dictionaries (see Table 8.96 on
page 717) describing the root fields to be imported (those with no ancestors in
the field hierarchy).
Rename
boolean
(Optional) A flag specifying whether fields imported from the template may be
renamed in the event of name conflicts with existing fields; see below for further
discussion. Default value: true.
The names of fields imported from a template may sometimes conflict with those
of existing fields in the target document. This can occur, for example, if the same
template page is imported more than once or if two different templates have fields
with the same names. If the Rename flag in the FDF template dictionary is true,
fields with such conflicting names are renamed to guarantee their uniqueness. If
Rename is false, the fields are not renamed; this results in multiple fields with the
same name in the target document. Each time the FDF file provides attributes for
a given field name, all fields with that name are updated. (See implementation
notes 137 and 138 in Appendix H.)
The TRef entry in an FDF template dictionary holds a named page reference
dictionary describing the location of external templates or page elements. Table
8.100 shows the contents of this type of dictionary.
TABLE 8.100 Entries in an FDF named page reference dictionary
KEY
TYPE
VALUE
Name
string
(Required) The name of the referenced page.
F
file specification
(Optional) The file containing the named page. If this entry is absent, it is
assumed that the page resides in the associated PDF file.
722
CHAPTER 8
Interactive Features
FDF Annotation Dictionaries
Each annotation dictionary in an FDF file must have a Page entry (see Table
8.101) indicating the page of the source document to which the annotation is
attached.
TABLE 8.101 Additional entry for annotation dictionaries in an FDF file
KEY
TYPE
VALUE
Page
integer
(Required for annotations in FDF files) The ordinal page number on which
this annotation should appear, where page 0 is the first page.
8.6.7
XFA Forms
PDF 1.5 introduces support for interactive forms based on the Adobe XML
Forms Architecture (XFA). The XFA entry in the interactive forms dictionary (see
Table 8.67) specifies an XFA resource, which is an XML stream that contains the
form information. The format of an XFA resource is described in the XML Data
Package (XDP) Specification (see the Bibliography).
The XFA entry may be either a stream containing the entire XFA resource or an
array specifying individual packets that together make up the XFA resource. The
resource includes but is not limited to the following information:
• The form template (specified in the template packet), which describes the char-
acteristics of the form, including its fields, calculations, validations, and for-
matting. The XML Template Specification describes the architecture of a form
template (see Bibliography).
• The data (specified in the datasets packet), which represents the state of the
form
• The configuration information (specified in the config packet), which is re-
quired to properly process the form template and associated data. Configura-
tion information is formatted as described in the XML Configuration
Specification (see Bibliography).
Each packet represents a complete XML element, with the exception of the first
and last packet, which specify begin and end tags for the xdp:xdp element. Exam-
ple 8.20 shows the XFA entry consisting of an array of packets; Example 8.21
shows the same entry specified as a stream.
Большое спасибо!
Ваше мнение очень важно для нас.
Нет комментариевНе стесняйтесь поделиться с нами вашим ценным мнением.
Текст