Repository navigation
PDF Spec 12 Forms
Part of: PDF-Spec-12-Interactive-Features
Navigation: PDF-Spec-12-Actions | PDF-Spec-Index | PDF-Spec-12-Signatures
| S | name | (Required) The type of action that this dictionary describes; shall be Rendition for a rendition action. | | R | dictionary | ( Required when OP is present with a value of 0 or 4; otherwise optional ) A rendition object (see 13.2.3, 'Renditions'). | | AN | dictionary | ( Required if OP is present with a value of 0, 1, 2, 3 or 4; otherwise optional ) An indirect reference to a screen annotation (see 12.5.6.18, 'Screen Annotations'). | | OP | integer | ( Required if JS is not present; otherwise optional ) The operation to perform when the action is triggered. Valid values shall be: 0 If no rendition is associated with the annotation specified by AN , play the rendition specified by R , associating it with the annotation. If a rendition is already associated with the annotation, it shall be stopped, and the new rendition shall be associated with the annotation. 1 Stop any rendition being played in association with the annotation specified by AN , and remove the association. If no rendition is being played, there is no effect. 2 Pause any rendition being played in association with the annotation specified b y AN . If no rendition is being played, there is no effect. 3 Resume any rendition being played in association with the annotation specified by AN . If no rendition is being played or the rendition is not paused, there is no effect. 4 Play the rendition specified by R , associating it with the annotation specified by AN. If a rendition is already associated with the annotation, resume the rendition if it is paused; otherwise, do nothing. | | JS | text string or stream | ( Required if OP is not present; otherwise optional ) A text string or stream containing a JavaScript script that shall be executed when the action is triggered. |
Either the JS entry or the OP entry shall be present. If both are present, OP is considered a fallback that shall be executed if the conforming reader is unable to execute JavaScripts. If OP has an unrecognized value and there is no JS entry, the action is invalid.
In some situations, a pause ( OP value of 2) or resume ( OP value of 3) operation may not make sense or the player may not support it. In such cases, the user should be notified of the failure to perform the operation.
Before a rendition action is executed, the conforming reader shall make sure that the P entry of the screen annotation dictionary references a valid page object and that the annotation is present in the page object's Annots array (see Table 30).
A rendition may play in the rectangle occupied by a screen annotation, even if the annotation itself is not visible; for example, if its Hidden or NoView flags (see Table 165) are set. If a screen annotation is not visible because its location on the page is not being displayed by the viewer, the rendition is not visible. However, it may become visible if the view changes, such as by scrolling.
A transition action (PDF 1.5) may be used to control drawing during a sequence of actions. As discussed in 12.6.2, 'Action Dictionaries,' the Next entry in an action dictionary may specify a sequence of actions. Conforming readers shall normally suspend drawing when such a sequence begins and resume drawing when it ends. If a transition action is present during a sequence, the conforming reader shall render the state of the page viewing area as it exists after completion of the previous action and display it using a transition specified in the action dictionary (see Table 215). Once this transition completes, drawing shall be suspended again.
Table 215 - Additional entries specific to a transition action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Trans for a transition action. |
| Trans | dictionary | (Required) The transition to use for the update of the display (see Table 162). |
A go-to-3D-view action (PDF 1.6) identifies a 3D annotation and specifies a view for the annotation to use (see 13.6, '3D Artwork'). Table 216 shows the entries in a go-to-3D-view action dictionary.
Table 216 - Additional entries specific to a go-to-3D-view action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be GoTo3DView for a transition action. |
| TA | dictionary | (Required) The target annotation for which to set the view. |
| V | (various) | (Required) The view to use. It may be one of the following types: A 3D view dictionary (see 13.6.4, '3D Views'). An integer specifying an index into the VA array in the 3D stream (see Table 300). A text string matching the IN entry in one of the views in the VA array (see Table 304). A name that indicates the first ( F ), last ( L ), next ( N ), previous ( P ), or default ( D ) entries in the VA array; see discussion following this Table. |
The V entry selects the view to apply to the annotation specified by TA . This view may be one of the predefined views specified by the VA entry of the 3D stream (see Table 300) or a unique view specified here.
If the predefined view is specified by the names N (next) or P (previous), it should be interpreted in the following way:
- When the last view applied was specified by means of the VA array, N and P indicate the next and previous entries, respectively, in the VA array (wrapping around if necessary).
- When the last view was not specified by means of VA , using N or P should result in reverting to the default view.
Upon invocation of a JavaScript action, a conforming processor shall execute a script that is written in the JavaScript programming language. Depending on the nature of the script, various interactive form fields in the document may update their values or change their visual appearances. Mozilla Development Center's ClientSide JavaScript Reference and the Adobe JavaScript for Acrobat API Reference (see the Bibliography) give details on the contents and effects of JavaScript scripts. Table 217 shows the action dictionary entries specific to this type of action.
Table 217 - Additional entries specific to a JavaScript action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be JavaScript for a JavaScript action. |
| JS | text string or text stream | (Required) A text string or text stream containing the JavaScript script to be executed. PDFDocEncoding or Unicode encoding (the latter identified by the Unicode prefix U + FEFF ) shall be used to encode the contents of the string or stream. |
To support the use of parameterized function calls in JavaScript scripts, the JavaScript entry in a PDF document's name dictionary (see 7.7.4, 'Name Dictionary') may 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 shall be 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.
An interactive form (PDF 1.2) -sometimes referred to as an AcroForm -is a collection of fields for gathering information interactively from the user. A PDF document may contain any number of fields appearing on any combination of pages, all of which make up a single, global interactive form spanning the entire document. Arbitrary subsets of these fields can be imported or exported from the document; see 12.7.5, 'Form Actions.'
NOTE 1 Interactive forms should not be confused with form XObjects (see 8.10, 'Form XObjects'). Despite the similarity of names, the two are different, unrelated types of objects.
Each field in a document's interactive form shall be defined by a field dictionary (see 12.7.3, 'Field Dictionaries'). For purposes of definition and naming, the fields can be organized hierarchically and can inherit attributes from their ancestors in the field hierarchy. A field's children in the hierarchy may also include widget annotations (see 12.5.6.19, 'Widget Annotations') that define its appearance on the page. A field that has children that are fields is called a non-terminal field . A field that does not have children that are fields is called a terminal field .
A terminal field may have children that are widget annotations (see 12.5.6.19, 'Widget Annotations') that define its appearance on the page. As a convenience, when a field has only a single associated widget annotation, the contents of the field dictionary and the annotation dictionary (12.5.2, 'Annotation Dictionaries') may be merged into a single dictionary containing entries that pertain to both a field and an annotation. (This presents no ambiguity, since the contents of the two kinds of dictionaries do not conflict.) If such an object defines an appearance stream, the appearance shall be consistent with the object's current value as a field.
- NOTE 2 Fields containing text whose contents are not known in advance may need to construct their appearance streams dynamically instead of defining them statically in an appearance dictionary; see 12.7.3.3, 'Variable Text.'
The contents and properties of a document's interactive form shall be defined by an interactive form dictionary that shall be referenced from the AcroForm entry in the document catalogue (see 7.7.2, 'Document Catalog'). Table 218 shows the contents of this dictionary.
Table 218 - Entries in the interactive form dictionary
| Key | Type | Value |
|---|---|---|
| Fields | array | (Required) An array of references to the document's root fields (those with no ancestors in the field hierarchy). |
| NeedAppearances | boolean | (Optional) A flag specifying whether to construct appearance streams and appearance dictionaries for all widget annotations in the document (see 12.7.3.3, 'Variable Text'). Default value: false . |
| SigFlags | integer | (Optional; PDF 1.3) A set of flags specifying various document- level characteristics related to signature fields (see Table 219, and 12.7.4.5, 'Signature Fields'). Default value: 0. |
| CO | array | (Required if any fields in the document have additional-actions dictionaries containing a C entry; PDF 1.3) An array of indirect references to field dictionaries with calculation actions, defining the calculation order in which their values will be recalculated when the value of any field changes (see 12.6.3, 'Trigger Events'). |
| DR | dictionary | (Optional) A resource dictionary (see 7.8.3, 'Resource Dictionaries') containing default resources (such as fonts, patterns, or colour spaces) that shall be used by form field appearance streams. At a minimum, this dictionary shall contain a Font entry specifying the resource name and font dictionary of the default font for displaying text. |
| DA | string | (Optional) A document-wide default value for the DA attribute of variable text fields (see 12.7.3.3, 'Variable Text'). |
| Q | integer | (Optional) A document-wide default value for the Q attribute of variable text fields (see 12.7.3.3, 'Variable Text'). |
| XFA | stream or array | (Optional; PDF 1.5) A stream or array containing an XFA resource , whose format shall be described by the Data Package (XDP) Specification . (see the Bibliography). The value of this entry shall be either a stream representing the entire contents of the XML Data Package or an array of text string and stream pairs representing the individual packets comprising the XML Data Package. See 12.7.8, 'XFA Forms,' for more information. |
The value of the interactive form dictionary's SigFlags entry is an unsigned 32-bit integer containing flags specifying various document-level characteristics related to signature fields (see 12.7.4.5, 'Signature Fields'). Bit positions within the flag word shall be numbered from 1 (low-order) to 32 (high-order). Table 219 shows the meanings of the flags; all undefined flag bits shall be reserved and shall be set to 0.
Table 219 - Signature flags
| Bit position | Name | Meaning |
|---|---|---|
| 1 | SignaturesExist | If set, the document contains at least one signature field. This flag allows a conforming reader to enable user interface items (such as menu items or pushbuttons) related to signature processing without having to scan the entire document for the presence of signature fields. |
| 2 | AppendOnly | If set, the document contains signatures that may be invalidated if the file is saved (written) in a way that alters its previous contents, as opposed to an incremental update. Merely updating the file by appending new information to the end of the previous version is safe (see H.7, 'Updating Example'). Conforming readers may use this flag to inform a user requesting a full save that signatures will be invalidated and require explicit confirmation before continuing with the operation. |
Each field in a document's interactive form shall be defined by a field dictionary , which shall be an indirect object. The field dictionaries may be organized hierarchically into one or more tree structures. Many field attributes are inheritable , meaning that if they are not explicitly specified for a given field, their values are taken from those of its parent in the field hierarchy. Such inheritable attributes shall be designated as such in the Tables 220 and 221. The designation (Required; inheritable) means that an attribute shall be defined for every field, whether explicitly in its own field dictionary or by inheritance from an ancestor in the hierarchy. Table 220 shows those entries that are common to all field dictionaries, regardless of type. Entries that pertain only to a particular type of field are described in the relevant sub-clauses in Table 220.
Table 220 - Entries common to all field dictionaries
| Key | Type | Value |
|---|---|---|
| FT | name | (Required for terminal fields; inheritable) The type of field that this dictionary describes: Btn Button (see 12.7.4.2, 'Button Fields') Tx Text (see 12.7.4.3, 'Text Fields') Ch Choice (see 12.7.4.4, 'Choice Fields') Sig (PDF 1.3) Signature (see 12.7.4.5, 'Signature Fields') This entry may be present in a non-terminal field (one whose descendants are fields) to provide an inheritable FT value. However, a non-terminal field does not logically have a type of its own; it is merely a container for inheritable attributes that are intended for descendant terminal fields of any type. |
| Parent | dictionary | (Required if this field is the child of another in the field hierarchy; absent otherwise) The field that is the immediate parent of this one (the field, if any, whose Kids array includes this field). A field can have at most one parent; that is, it can be included in the Kids array of at most one other field. |
Table 220 - Entries common to all field dictionaries (continued)
| Key | Type | Value |
|---|---|---|
| Kids | array | (Sometimes required, as described below) An array of indirect references to the immediate children of this field. In a non-terminal field, the Kids array shall refer to field dictionaries that are immediate descendants of this field. In a terminal field, the Kids array ordinarily shall refer to one or more separate widget annotations that are associated with this field. However, if there is only one associated widget annotation, and its contents have been merged into the field dictionary, Kids shall be omitted. |
| T | text string | (Optional) The partial field name (see 12.7.3.2, 'Field Names'). |
| TU | text string | (Optional; PDF 1.3) An alternate field name that shall be used in place of the actual field name wherever the field shall be identified in the user interface (such as in error or status messages referring to the field). This text is also useful when extracting the document's contents in support of accessibility to users with disabilities or for other purposes (see 14.9.3, 'Alternate Descriptions'). |
| TM | text string | (Optional; PDF 1.3) The mapping name that shall be used when exporting interactive form field data from the document. |
| Ff | integer | (Optional; inheritable) A set of flags specifying various characteristics of the field (see Table 221). Default value: 0. |
| V | (various) | (Optional; inheritable) The field's value, whose format varies depending on the field type. See the descriptions of individual field types for further information. |
| DV | (various) | (Optional; inheritable) The default value to which the field reverts when a reset-form action is executed (see 12.7.5.3, 'Reset-Form Action'). The format of this value is the same as that of V . |
| AA | dictionary | (Optional; PDF 1.2) An additional-actions dictionary defining the field's behaviour in response to various trigger events (see 12.6.3, 'Trigger Events'). This entry has exactly the same meaning as the AA entry in an annotation dictionary (see 12.5.2, 'Annotation Dictionaries'). |
The value of the field dictionary's Ff entry is an unsigned 32-bit integer containing flags specifying various characteristics of the field. Bit positions within the flag word shall be numbered from 1 (low-order) to 32 (highorder). The flags shown in Table 221 are common to all types of fields. Flags that apply only to specific field types are discussed in the sub-clauses describing those types. All undefined flag bits shall be reserved and shall be set to 0.
Table 221 - Field flags common to all field types
| Bit position | Name | Meaning |
|---|---|---|
| 1 | ReadOnly | If set, the user may not change the value of the field. Any associated widget annotations will not interact with the user; that is, they will not respond to mouse clicks or change their appearance in response to mouse motions. This flag is useful for fields whose values are computed or imported from a database. |
| 2 | Required | If set, the field shall have a value at the time it is exported by a submit- form action (see 12.7.5.2, 'Submit-Form Action'). |
| 3 | NoExport | If set, the field shall not be exported by a submit-form action (see 12.7.5.2, 'Submit-Form Action'). |
The T entry in the field dictionary (see Table 220) holds a text string defining the field's partial field name . The fully qualified field name is not explicitly defined but shall be 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 shall be formed by appending the child field's partial name to the parent's fully qualified name, separated by a PERIOD (2Eh) as shown:
parent's_full_name . child's_partial_name
- EXAMPLE If a field with the partial field name PersonalData 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
PersonalData . Address . ZipCode
Because the PERIOD is used as a separator for fully qualified names, a partial name shall not contain a PERIOD character. Thus, all fields descended from a common ancestor share the ancestor's fully qualified field name as a common prefix in their own fully qualified names.
It is possible for different field dictionaries to have the same fully qualified field name if they are descendants of a common ancestor with that name and have no partial field names ( T entries) of their own. Such field dictionaries are different representations of the same underlying field; they should differ only in properties that specify their visual appearance. In particular, field dictionaries with the same fully qualified field name shall have the same field type ( FT ), value ( V ), and default value ( DV ).
When the contents and properties of a field are known in advance, its visual appearance can be specified by an appearance stream defined in the PDF file (see 12.5.5, 'Appearance Streams,' and 12.5.6.19, 'Widget Annotations'). In some cases, however, the field may contain text whose value is not known until viewing time.
- NOTE Examples include text fields to be filled in with text typed by the user from the keyboard, scrollable list boxes whose contents are determined interactively at the time the document is displayed and fields containing current dates or values calculated by a JavaScript.
In such cases, the PDF document cannot provide a statically defined appearance stream for displaying the field. Instead, the conforming reader shall construct an appearance stream dynamically at viewing time. The dictionary entries shown in Table 222 provide general information about the field's appearance that can be combined with the specific text it contains to construct an appearance stream.
Table 222 - Additional entries common to all fields containing variable text
| Key | Type | Value |
|---|---|---|
| DA | string | (Required; inheritable) The default appearance string containing a sequence of valid page-content graphics or text state operators that define such properties as the field's text size and colour. |
| Q | integer | (Optional; inheritable) A code specifying the form of quadding (justification) that shall be used in displaying the text: 0 Left-justified 1 Centered 2 Right-justified Default value: 0 (left-justified). |
| DS | text string | (Optional; PDF 1.5) A default style string, as described in 12.7.3.4, 'Rich Text Strings.' |
Table 222 - Additional entries common to all fields containing variable text (continued)
| Key | Type | Value |
|---|---|---|
| RV | text string or text stream | (Optional; PDF 1.5) A rich text string, as described in 12.7.3.4, 'Rich Text Strings.' |
The new appearance stream becomes the normal appearance ( N ) in the appearance dictionary associated with the field's widget annotation (see Table 168). (If the widget annotation has no appearance dictionary, the conforming reader shall create one and store it in the annotation dictionary's AP entry.)
In PDF 1.5, form fields that have the RichText flag set (see Table 226) specify formatting information as described in 12.7.3.4, 'Rich Text Strings.' For these fields, the following conventions are not used, and the entire annotation appearance shall be regenerated each time the value is changed.
For non-rich text fields, the appearance stream-which, like all appearance streams, is a form XObject-has the contents of its form dictionary initialized as follows:
- The resource dictionary ( Resources ) shall be created using resources from the interactive form dictionary's DR entry (see Table 218).
- The lower-left corner of the bounding box ( BBox ) is set to coordinates (0, 0) in the form coordinate system. The box's top and right coordinates are taken from the dimensions of the annotation rectangle (the Rect entry in the widget annotation dictionary).
- All other entries in the appearance stream's form dictionary are set to their default values (see 8.10, 'Form XObjects').
EXAMPLE The appearance stream includes the following section of marked content, which represents the portion of the stream that draws the text:
/Tx BMC % Begin marked content with tag Tx q % Save graphics state … Any required graphics state changes, such as clipping … BT % Begin text object … Default appearance string ( DA ) … … Text-positioning and text-showing operators to show the variable text … ET % End text object Q % Restore graphics state EMC % End marked content
The BMC (begin marked content) and EMC (end marked content) operators are discussed in 14.6, 'Marked Content.' q (save graphics state) and Q (restore graphics state) are discussed in 8.4.4, 'Graphics State Operators.' BT (begin text object) and ET (end text object) are discussed in 9.4, 'Text Objects.' See Example 1 in 12.7.8, 'XFA Forms' for an example.
The default appearance string ( DA ) contains any graphics state or text state operators needed to establish the graphics state parameters, such as text size and colour, for displaying the field's variable text. Only operators that are allowed within text objects shall occur in this string (see Figure 9). At a minimum, the string shall include a Tf (text font) operator along with its two operands, font and size . The specified font value shall match a resource name in the Font entry of the default resource dictionary (referenced from the DR entry of the interactive form dictionary; see Table 218). A zero value for size means that the font shall be auto-sized : its size shall be computed as a function of the height of the annotation rectangle.
The default appearance string shall contain at most one Tm (text matrix) operator. If this operator is present, the conforming reader shall replace the horizontal and vertical translation components with positioning values it determines to be appropriate, based on the field value, the quadding ( Q ) attribute, and any layout rules it employs. If the default appearance string contains no Tm operator, the viewer shall insert one in the appearance stream (with appropriate horizontal and vertical translation components) after the default appearance string and before the text-positioning and text-showing operators for the variable text.
To update an existing appearance stream to reflect a new field value, the conforming reader shall first copy any needed resources from the document's DR dictionary (see Table 218) into the stream's Resources dictionary. (If the DR and Resources dictionaries contain resources with the same name, the one already in the Resources dictionary shall be left intact, not replaced with the corresponding value from the DR dictionary.) The conforming reader shall then replace the existing contents of the appearance stream from /Tx BMC to the matching EMC with the corresponding new contents as shown in Example 1 in "Check Boxes," 12.7.4, 'Field Types.' (If the existing appearance stream contains no marked content with tag Tx, the new contents shall be appended to the end of the original stream.)
Beginning with PDF 1.5, the text contents of variable text form fields, as well as markup annotations, may include formatting (style) information. These rich text strings are fully-formed XML documents that conform to the rich text conventions specified for the XML Forms Architecture (XFA) specification, which is itself a subset of the XHTML 1.0 specification, augmented with a restricted set of CSS2 style attributes (see the Bibliography for references to all these standards).
Table 223 lists the XHTML elements that may appear in rich text strings. The <body> element is the root element; its required attributes are listed in Table 224. Other elements (<p> and <span>) contain enclosed text that may take style attributes, which are listed in Table 225. These style attributes are CSS inline style property declarations of the form name : value , with each declaration separated by a SEMICOLON (3Bh), as illustrated in the Example in "Radio Buttons," 12.7.4, 'Field Types.'
In PDF 1.6, PDF supports the rich text elements and attributes specified in the XML Forms Architecture (XFA) Specification, 2.2 (see Bibliography). These rich text elements and attributes are a superset of those described in Table 223, Table 224 and Table 225. In PDF 1.7, PDF supports the rich text elements and attributes specified in the XML Forms Architecture (XFA) Specification, 2.4 (see Bibliography).
Table 223 - XHTML elements used in rich text strings
| element | Description |
|---|---|
| The element at the root of the XML document. Table 224 lists the required attributes for this element. | |
| Encloses text that shall be interpreted as a paragraph. It may take the style attributes listed in Table 225. | |
| Encloses text that shall be displayed in an italic font. | |
| Encloses text that shall be displayed in a bold font. | |
| Groups text solely for the purpose of applying styles (using the attributes in Table 225). |
Table 224 - Attributes of the <body> element
| Attribute | Description |
|---|---|
| xmlns | The default namespaces for elements within the rich text string. Shall be xmlns="http://www.w3.org/1999/xhtml" xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0". |
| xfa:contentType | Shall be "text/html". |
Table 224 - Attributes of the <body> element (continued)
| Attribute | Description |
|---|---|
| xfa:APIVersion | A string that identifies the software used to generate the rich text string. It shall be of the form software_name:software_version, where software_name identifies the software by name. It shall not contain spaces. software_version identifies the version of the software. It consists of a series of integers separated by decimal points. Each integer is a version number, the leftmost value being a major version number, with values to the right increasingly minor. When comparing strings, the versions shall be compared in order. NOTE '5.2' is less than '5.13' because 2 is less than 13; the string is not treated as a decimal number. When comparing strings with different numbers of sections, the string with fewer sections is implicitly padded on the right with sections containing '0' to make the number of sections equivalent. |
| xfa:spec | The version of the XML Forms Architecture (XFA) specification to which the rich text string complies. If the file being written conforms to PDF 1.5, then the rich text string shall conform to XFA 2.0, and this attribute shall be XFA 2.0; if the file being written conforms to PDF 1.6, then the rich text string shall conform to XFA 2.2, and this attribute shall be XFA 2.2; and if the file being written conforms to PDF 1.7, then the rich text string shall conform to XFA 2.4, and this attribute shall be XFA 2.4. |
Table 225 - CSS2 style attributes used in rich text strings
| Attribute | Value | Description |
|---|---|---|
| text-align | keyword | Horizontal alignment. Possible values: left, right, and center. |
| vertical-align | decimal | An amount by which to adjust the baseline of the enclosed text. A positive value indicates a superscript; a negative value indicates a subscript. The value is of the form pt, optionally preceded by a sign, and followed by 'pt'. EXAMPLE -3pt, 4pt. |
| font-size | decimal | The font size of the enclosed text. The value is of the form pt. |
| font-style | keyword | Specifies the font style of the enclosed text. Possible values: normal, italic. |
| font-weight | keyword | The weight of the font for the enclosed text. Possible values: normal, bold, 100, 200, 300, 400, 500, 600, 700, 800, 900. normal is equivalent to 400, and bold is equivalent to 700. |
| font-family | list | A font name or list of font names that shall be used to display the enclosed text. (If a list is provided, the first one containing glyphs for the specified text shall be used.) |
| font | list | A shorthand CSS font property of the form font: |
| color | RGB value | The colour of the enclosed text. It can be in one of two forms: # rrggbb with a 2-digit hexadecimal value for each component rgb (rrr,ggg,bbb) with a decimal value for each component. Although the values specified by the color property are interpreted as sRGB values, they shall be transformed into values in a non-ICC based colour space when used to generate the annotation's appearance. |
Table 225 - CSS2 style attributes used in rich text strings (continued)
| Attribute | Value | Description |
|---|---|---|
| text-decoration | keyword | One of the following keywords: underline: The enclosed text shall be underlined. line-through: The enclosed text shall have a line drawn through it. |
| font-stretch | keyword | Specifies a normal, condensed or extended face from a font family. Supported values from narrowest to widest are ultra-condensed, extra-condensed, condensed, semi-condensed, normal, semi- expanded, expanded, extra-expanded, and ultra-expanded. |
Rich text strings shall be specified by the RV entry of variable text form field dictionaries (see Table 222) and the RC entry of markup annotation dictionaries (see Table 170). Rich text strings may be packaged as text streams (see 7.9.3, 'Text Streams'). Form fields using rich text streams should also have the RichText flag set (see Table 228).
A default style string shall be specified by the DS entry for free text annotations (see Table 174) or variable text form fields (see Table 222). This string specifies the default values for style attributes, which shall be used for any style attributes that are not explicitly specified for the annotation or field. All attributes listed in Table 225 are legal in the default style string. This string, in addition to the RV or RC entry, shall be used to generate the appearance.
NOTE 1
Markup annotations other than free text annotations (see 12.5.6.2, 'Markup Annotations') do not use a default style string because their appearances are implemented using platform controls requiring the conforming reader to pick an appropriate 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 readers 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.
When a rich text string specifies font attributes, the conforming reader shall use font name selection as described in Section 15.3 of the CSS2 specification (see the Bibliography). Precedence should be given to the fonts in the default resources dictionary, as specified by the DR entry in Table 218.
EXAMPLE
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 default font; the second paragraph changes the font size.
/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> )
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 keyboard.
- 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 digital signatures and optional data for authenticating the name of the signer and the document's contents.
The following sub-clauses describe each of these field types in detail. Further types may be added in the future.
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 12.7.4.2.2, 'Pushbuttons').
- A check box toggles between two states, on and off (see 12.7.4.2.3, 'Check Boxes').
- 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 selecting any one of the buttons automatically deselects all the others. (There are exceptions to this rule, as noted in "Radio Buttons.")
For button fields, bits 15, 16, 17, and 26 shall indicate the intended behaviour of the button field. A conforming reader shall follow the intended behaviour, as defined in Table 226 and clauses 12.7.4.2.2, "Pushbuttons", 12.7.4.2.3, "Check Boxes" and 12.7.4.2.4, "Radio Buttons".
Table 226 - Field flags specific to button fields
| 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 check box. 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 | (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 exclusive (the same behavior as HTML radio buttons). |
A pushbutton field shall have a field type of Btn and the Pushbutton flag (see Table 226) set to one. Because this type of button retains no permanent value, it shall not use the V and DV entries in the field dictionary (see Table 220).
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 shall be Btn and its Pushbutton and Radio flags (see Table 226) shall both be clear. Each state can have a separate appearance, which shall be defined by an appearance stream in the appearance dictionary of the field's widget annotation (see 12.5.5, 'Appearance Streams'). The appearance for the off state is optional but, if present, shall be stored in the appearance dictionary under the name Off . Yes should be used as the name for the on state.
The V entry in the field dictionary (see Table 220) holds a name object representing the check box's appearance state, which shall be used to select the appropriate appearance from the appearance dictionary.
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
EXAMPLE 1 This example shows a typical check box definition.
Beginning with PDF 1.4, the field dictionary for check boxes and radio buttons may contain an optional Opt entry (see Table 227). If present, the Opt entry shall be an array of text strings representing the export value of each annotation in the field. It may be used for the following purposes:
- To represent the export values of check box and radio button fields in non-Latin writing systems. Because name objects in the appearance dictionary are limited to PDFDocEncoding , they cannot represent nonLatin text.
- To allow radio buttons or check boxes to be checked independently, even if they have the same export value.
- EXAMPLE 2
A group of check boxes may be duplicated on more than one page such that the desired behavior is that when a user checks a box, the corresponding boxes on each of the other pages are 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 shall occur only if the RadiosInUnison flag is set. If it is not set, at most one radio button in a field shall be set at a time.
Table 227 - Additional entry specific to check box and radio button fields
| Key | Type | Value |
|---|---|---|
| Opt | array of text strings | (Optional; inheritable; PDF 1.4) An array containing one entry for each widget annotation in the Kids array of the radio button or check box field. Each entry shall be 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 (for example, /1, /2) numerical position (starting with 0 ) of the annotation in the Kids array, encoded as a name object. This allows distinguishing between the annotations even if two or more of them have the same value in the Opt array. |
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 most one button in the on state at any given time; selecting any of the buttons automatically 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 226) is clear, and the Radio flag is set. This type of button field has an additional flag, NoToggleToOff, which specifies, if set, that exactly one of the radio buttons shall be selected 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 220) 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 appearance state of whichever child field is currently in the on state; the default value for this entry is Off.
EXAMPLE This example shows the object definitions for a set of radio buttons.
% Radio button field % … Radio flag = 1, Pushbutton = 0 … /T ( Credit card )
10 0 obj << /FT /Btn /Ff … /V /cardbrand1 /Kids [ 11 0 R 12 0 R ]
>> endobj 11 0 obj % First radio button << /Parent 10 0 R /AS /cardbrand1 /AP << /N << /cardbrand1 8 0 R /Off 9 0 R >> >> >> endobj 12 0 obj % Second radio button << /Parent 10 0 R /AS /Off /AP << /N << /cardbrand2 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 may use the optional Opt entry in the field dictionary (PDF 1.4) to define export values for its constituent radio buttons, using Unicode (UTF-16BE) encoding for non-Latin characters (see Table 227).
A text field (field type Tx ) is a box or space for text fill-in data typically entered from a 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 dictionary's Ff entry. Table 228 shows the flags pertaining to this type of field. A text field shall have a field type of Tx . A conforming PDF file, and a conforming processor shall obey the usage guidelines in Table 228.
Table 228 - Field flags specific to text fields
| Bit position | Name | Meaning |
|---|---|---|
| 13 | Multiline | If set, the field may contain multiple lines of text; if clear, the field's text shall be 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 shall instead be echoed in some unreadable form, such as asterisks or bullet characters. NOTE To protect password confidentiality, readers 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 shall be submitted as the value of the field. |
| 23 | DoNotSpellCheck | (PDF 1.4) If set, text entered in the field shall not be spell-checked. |
| 24 | DoNotScroll | (PDF 1.4) If set, the field shall 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 shall be accepted for interactive form filling; for non- interactive form filling, the filler should take care not to add more character than will visibly fit in the defined area. |
| 25 | Comb | (PDF 1.5) May be set only if the MaxLen entry is present in the text field dictionary (see Table 229) and if the Multiline, Password, and FileSelect flags are clear. If set, the field shall be 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 shall be a rich text string (see 12.7.3.4, 'Rich Text Strings'). If the field has a value, the RV entry of the field dictionary (Table 222) shall specify the rich text string. |
The field's text shall be 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 shall be used to construct an appearance stream for displaying the field, as described under 12.7.3.3, 'Variable Text.' The text shall be presented in a single style (font, size, colour, and so forth), as specified by the DA (default appearance) string.
If the FileSelect flag (PDF 1.4) is set, the field shall function as a file-select control . In this case, the field's text represents the pathname of a file whose contents shall be submitted as the field's value:
- For fields submitted in HTML Form format, the submission shall use the MIME content type multipart / formdata, as described in Internet RFC 2045, Multipurpose 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 in 12.7.7.3, 'FDF Catalog') shall be a file specification (7.11, 'File Specifications') identifying the selected file.
- XML format is not supported for file-select controls; therefore, no value shall be submitted in this case.
Besides the usual entries common to all fields (see Table 220) and to fields containing variable text (see Table 222), the field dictionary for a text field may contain the additional entry shown in Table 229.
Table 229 - 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
The following example shows the object definitions for a typical text field.
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 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
A choice field shall have a field type of Ch that contains several text items, one or more of which shall be selected as the field value. The items may be presented to the user in one of the following two forms:
- A scrollable list box
- A combo box consisting of a drop-down list. The combo box may be accompanied by an editable text box in which the user can type a value other than the predefined choices, as directed by the value of the Edit bit in the Ff entry.
Table 230 - 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 shall include an editable text box as well as a drop-down list; if clear, it shall include only a drop-down list. This flag shall be used only if the Combo flag is set. |
Table 230 - Field flags specific to choice fields (continued)
| Bit position | Name | Meaning |
|---|---|---|
| 20 | Sort | If set, the field's option items shall be sorted alphabetically. This flag is intended for use by writers, not by readers. Conforming readers shall display the options in the order in which they occur in the Opt array (see Table 231). |
| 22 | MultiSelect | (PDF 1.4) If set, more than one of the field's option items may be selected simultaneously; if clear, at most one item shall be selected. |
| 23 | DoNotSpellCheck | (PDF 1.4) If set, text entered in the field shall not be spell- checked. This flag shall not be used unless the Combo and Edit flags are both set. |
| 27 | CommitOnSelChange | (PDF 1.5) If set, the new value shall be committed as soon as a selection is made (commonly with the pointing device). In this case, supplying a value for a field involves three actions: selecting the field for fill-in, selecting a choice for the fill-in value, and leaving that field, which finalizes or 'commits' the data choice and triggers any actions associated with the entry or changing of this data. If this flag is on, then processing does not wait for leaving the field action to occur, but immediately proceeds to the third step. 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 230. Table 231 shows the field dictionary entries specific to choice fields.
Table 231 - Additional entries specific to a choice field
| Key | Type | Value |
|---|---|---|
| Opt | array | (Optional) An array of options that shall 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 that shall be displayed as the name of the option. 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, representing the zero-based indices in the Opt array of the currently selected option items. This entry shall be used 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. This entry should not be used for choice fields that do not allow multiple selection. If the items identified by this entry differ from those in the V entry of the field dictionary (see discussion following this Table), the V entry shall be used. |
The Opt array specifies the list of options in the choice field, each of which shall be represented by a text string that shall be displayed on the screen. Each element of the Opt array contains either this text string by itself or a two-element array, whose second element is the text string and whose first element is a text string representing the export value that shall be used when exporting interactive form field data from the document.
The field dictionary's V (value) entry (see Table 220) identifies the item or items currently selected in the choice field. If the field does not allow multiple 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 represented 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 The following example shows a typical choice field definition.
<< /FT /Ch /Ff … /T ( Body Color ) /V ( Blue ) /Opt [ ( Red ) ( My favorite color ) ( Blue ) ] >>
A signature field (PDF 1.3) is a form field that contains a digital signature (see 12.8, 'Digital Signatures'). The field dictionary representing a signature field may contain the additional entries listed in Table 232, as well as the standard entries described in Table 220. The field type ( FT ) shall be Sig , and the field value ( V ), if present, shall be a signature dictionary containing the signature and specifying various attributes of the signature field (see Table 252).
NOTE 1 This signature form field serves two primary purposes. The first is to define the form field that will provide the visual signing properties for display but it also may hold information needed later when the actual signing takes place, such as the signature technology to use. This carries information from the author of the document to the software that later does the signing.
- NOTE 2 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 signature field typically exports the T , V , and AP entries.
Like any other field, a signature field may be described by a widget annotation dictionary containing entries pertaining to an annotation as well as a field (see 12.5.6.19, 'Widget Annotations'). The annotation rectangle ( Rect ) in such a dictionary shall give the position of the field on its page. Signature fields that are not intended to be visible shall have an annotation rectangle that has zero height and width. Conforming readers shall treat such signatures as not visible. Conforming readers shall also treat signatures as not visible if either the Hidden bit or the NoView bit of the F entry is true . The F entry is described in Table 164, and annotation flags are described in Table 165.
The appearance dictionary ( AP ) of a signature field's widget annotation defines the field's visual appearance on the page (see 12.5.5, 'Appearance Streams').
Table 232 - Additional entries specific to a signature field
| Key | Type | Value |
|---|---|---|
| Lock | dictionary | (Optional; shall be an indirect reference; PDF 1.5) A signature field lock dictionary that specifies a set of form fields that shall be locked when this signature field is signed. Table 233 lists the entries in this dictionary. |
| SV | dictionary | (Optional; shall be an indirect reference; PDF 1.5) A seed value dictionary (see Table 234) containing information that constrains the properties of a signature that is applied to this field. |
The signature field lock dictionary (described in Table 233) contains field names from the signature seed value dictionary (described in Table 234) that cannot be changed through the user interface of a conforming reader.
Table 233 - Entries in a signature field lock dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall 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. The value shall be one of the following: 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. |
The value of the SV entry in the field dictionary is a seed value dictionary whose entries (see Table 234) provide constraining information that shall be used at the time the signature is applied. Its Ff entry specifies whether the other entries in the dictionary shall be honoured or whether they are merely recommendations.
The seed value dictionary may include seed values for private entries belonging to multiple handlers. A given handler shall use only those entries that are pertinent to itself and ignore the others.
Table 234 - 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, shall be SV for a seed value dictionary. |
| 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 optional constraint. Bit positions are 1 ( Filter ); 2 ( SubFilter ); 3 ( V ); 4 ( Reasons ); 5 ( LegalAttestation ); 6 ( AddRevInfo ); and 7 ( DigestMethod ). Default value: 0. |
| Filter | name | (Optional) The signature handler that shall be used to sign the signature field. Beginning 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 shall be used when signing; otherwise, signing shall not take place. If Ff indicates that this is an optional constraint, this handler may be used if it is available. If it is not available, a different handler may 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 shall 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 shall be used when signing; otherwise, signing shall not take place. If Ff indicates that this is an optional constraint, then the first matching encoding shall be used if it is available. If none is available, a different encoding may be used. |
| DigestMethod | array | ( Optional; PDF 1.7 ) An array of names indicating acceptable digest algorithms to use while signing. The value shall be one of SHA1 , SHA256 , SHA384 , SHA512 and RIPEMD160 . The default value is implementation-specific. This property is only applicable if the digital credential signing contains RSA public/private keys. If it contains DSA public/ private keys, the digest algorithm is always SHA1 and this attribute shall be ignored. |
Table 234 - Entries in a signature field seed value dictionary (continued)
| Key | Type | Value |
|---|---|---|
| V | real | (Optional) The minimum required capability of the signature field seed value dictionary parser. A value of 1 specifies that the parser shall be able to recognize all seed value dictionary entries in a PDF 1.5 file. A value of 2 specifies that it shall be able to recognize all seed value dictionary entries specified. The Ff entry indicates whether this shall be treated as a required constraint. |
| Cert | dictionary | (Optional) A certificate seed value dictionary (see Table 235) containing information about the characteristics of the certificate that shall 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 conforming products. If the Reasons array is provided and the Ff entry indicates that Reasons is a required constraint, one of the reasons in the array shall be used for the signature dictionary; otherwise, signing shall not take place. If the Ff entry indicates Reasons is an optional constraint, one of the reasons in the array may be chosen or a custom reason can be provided. If the Reasons array is omitted or contains a single entry with the value PERIOD (2Eh) and the Ff entry indicates that Reasons is a required constraint, the Reason entry shall be omitted from the signature dictionary (see Table 252). |
| 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 author signature (see 12.8, 'Digital Signatures'). The values 1 through 3 shall be used for certification signatures and correspond to the value of P in a DocMDP transform parameters dictionary (see Table 254). If this MDP key is not present or the MDP dictionary does not contain a P entry, no rules shall be defined regarding the type of signature or its permissions. |
| 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 Bibliography). Ff An integer whose value is 1 (the signature shall have a time stamp) or 0 (the signature need not have a time stamp). Default value: 0. NOTE Please see 12.8.3.3, "PKCS#7 Signatures as used in ISO 32000" for more details about hashing. |
| LegalAttestation | array | (Optional; PDF 1.6) An array of text strings specifying possible legal attestations (see 12.8.5, 'Legal Content Attestations'). The value of the corresponding flag in the Ff entry indicates whether this is a required constraint. |
Table 234 - Entries in a signature field seed value dictionary (continued)
| Key | Type | Value |
|---|---|---|
| AddRevInfo | boolean | ( Optional; PDF 1.7 ) A flag indicating whether revocation checking shall be carried out. If AddRevInfo is true , the conforming processor shall perform the following additional tasks when signing the signature field: Perform revocation checking of the certificate (and the corresponding issuing certificates) used to sign. Include the revocation information within the signature value. Three SubFilter values have been defined for ISO 32000. For those values the AddRevInfo value shall be true only if SubFilter is adbe.pkcs7.detached or adbe.pkcs7.sha1 . If SubFilter is x509.rsa_sha1 , this entry shall be omitted or set to false . Additional SubFilters may be defined that also use AddRevInfo values. If AddRevInfo is true and the Ff entry indicates this is a required constraint, then the preceding tasks shall be performed. If they cannot be performed, then signing shall fail. Default value: false NOTE 1 Revocation information is carried in the signature data as specified by PCKS#7. See 12.8.3.3, "PKCS#7 Signatures as used in ISO 32000". NOTE 2 The trust anchors used are determined by the signature handlers for both creation and validation. |
For optional keys that are not present, no constraint shall be placed upon the signature handler for that property when signing.
Table 235 - Entries in a certificate seed value dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be SVCert for a certificate seed value dictionary. |
| 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 shall be 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. |
| Subject | array | (Optional) An array of byte strings containing DER-encoded X.509v3 certificates that are acceptable for signing. X.509v3 certificates are described in RFC 3280, Internet X.509 Public Key Infrastructure, Certificate and Certificate Revocation List (CRL) Profile (see the Bibliography). The value of the corresponding flag in the Ff entry indicates whether this is a required constraint. |
Table 235 - Entries in a certificate seed value dictionary (continued)
| Key | Type | Value |
|---|---|---|
| SubjectDN | array of dictionaries | ( Optional; PDF 1.7 ) An array of dictionaries, each specifying a Subject Distinguished Name (DN) that shall be present within the certificate for it to be acceptable for signing. The certificate ultimately used for the digital signature shall contain all the attributes specified in each of the dictionaries in this array. (PDF keys and values are mapped to certificate attributes and values.) The certificate is not constrained to use only attribute entries from these dictionaries but may contain additional attributes.The Subject Distinguished Name is described in RFC 3280 (see the Bibliography). The key can be any legal attribute identifier (OID). Attribute names shall contain characters in the set a-z A-Z 0-9 and PERIOD. Certificate attribute names are used as key names in the dictionaries in this array. Values of the attributes are used as values of the keys. Values shall be text strings. The value of the corresponding flag in the Ff entry indicates whether this entry is a required constraint. |
| KeyUsage | array of ASCII strings | ( Optional; PDF 1.7 ) An array of ASCII strings, where each string specifies an acceptable key-usage extension that shall be present in the signing certificate. Multiple strings specify a range of acceptable key- usage extensions. The key-usage extension is described in RFC 3280. 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 string, 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 shall be ignored. Any missing characters or characters that are not one of the following values, shall be treated as 'X'. The following character values shall be supported: 0 Corresponding key-usage shall not be set. 1 Corresponding key-usage shall be set. X State of the corresponding key-usage does not matter. EXAMPLE 1 The string values ' 1 ' and ' 1XXXXXXXX ' represent settings where the key-usage type digitalSignature is 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 |
| Issuer | array | (Optional) An array of byte strings containing DER-encoded X.509v3 certificates of acceptable issuers. If the signer's certificate refers to any of the specified issuers (either directly or indirectly), the certificate shall be considered acceptable for signing. The value of the corresponding flag in the Ff entry indicates whether this is a required constraint. This array may contain self-signed certificates. |
| OID | array | (Optional) An array of byte strings that contain Object Identifiers (OIDs) of the certificate policies that shall be present in the signing certificate. EXAMPLE 2 An example of such a string is: (2.16.840.1.113733.1.7.1.1). This field shall only be used 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. |
Table 235 - Entries in a certificate seed value dictionary (continued)
| Key | Type | Value |
|---|---|---|
| URL | ASCII string | (Optional) A URL, the use for which shall be defined by the URLType entry. |
| 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 shall 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 shall be ignored for this usage. Third parties may extend the use of this attribute with their own attribute values, which shall conform to the guidelines described in Annex E. The default value is Browser . |
Interactive forms also support special types of actions in addition to those described in 12.6.4, 'Action Types':
- submit-form action
- reset-form action
- import-data action
Upon invocation of a submit-form action , a conforming processor shall transmit the names and values of selected interactive form fields to a specified uniform resource locator (URL),
NOTE Presumably, the URL is the address of a Web server that will process them and send back a response.
The value of the action dictionary's Flags entry shall be an non-negative integer containing flags specifying various characteristics of the action. Bit positions within the flag word shall be numbered starting with 1 (low-order). Table 237 shows the meanings of the flags; all undefined flag bits shall be reserved and shall be set to 0.
Table 236 - Additional entries specific to a submit-form action
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be SubmitForm for a submit-form action. |
| F | file specification | (Required) A URL file specification (see 7.11.5, 'URL Specifications') giving the uniform resource locator (URL) of the script at the Web server that will process the submission. |
Table 236 - Additional entries specific to a submit-form action (continued)
| Key | Type | Value |
|---|---|---|
| Fields | array | (Optional) An array identifying which fields to include in the submission or which to exclude, depending on the setting of the Include/Exclude flag in the Flags entry (see Table 237). Each element of the array shall be 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 shall be ignored, and all fields in the document's interactive form shall be submitted except those whose NoExport flag (see Table 221) is set. Fields with no values may also be excluded, as dictated by the value of the IncludeNoValueFields flag; see Table 237. |
| Flags | integer | (Optional; inheritable) A set of flags specifying various characteristics of the action (see Table 237). Default value: 0. |
Table 237 - Flags for submit-form actions
| Bit position | Name | Meaning |
|---|---|---|
| 1 | Include/Exclude | If clear, the Fields array (see Table 236) specifies which fields to include in the submission. (All descendants of the specified fields in the field hierarchy shall be submitted as well.) If set, the Fields array tells which fields to exclude. All fields in the document's interactive form shall be submitted except those listed in the Fields array and those whose NoExport flag (see Table 221) is set and fields with no values if the IncludeNoValueFields flag is clear. |
| 2 | IncludeNoValueFields | If set, all fields designated by the Fields array and the Include/Exclude flag shall be submitted, regardless of whether they have a value ( V entry in the field dictionary). For fields without a value, only the field name shall be transmitted. If clear, fields without a value shall not be submitted. |
| 3 | ExportFormat | Meaningful only if the SubmitPDF and XFDF flags are clear. If set, field names and values shall be submitted in HTML Form format. If clear, they shall be submitted in Forms Data Format (FDF); see 12.7.7, 'Forms Data Format.' |
| 4 | GetMethod | If set, field names and values shall be submitted using an HTTP GET request. If clear, they shall be submitted using a POST request. This flag is meaningful only when the ExportFormat flag is set; if ExportFormat is clear, this flag shall also be clear. |
Table 237 - Flags for submit-form actions (continued)
| Bit position | Name | Meaning |
|---|---|---|
| 5 | SubmitCoordinates | If set, the coordinates of the mouse click that caused the submit-form action shall be transmitted as part of the form data. The coordinate values are relative to the upper-left corner of the field's widget annotation rectangle. They shall be 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 ASCII SPACE (20h) character, both the name and the ASCII PERIOD (2Eh) following it shall be suppressed, resulting in the format x= xval &y= yval This flag shall be used only when the ExportFormat flag is set. If ExportFormat is clear, this flag shall also be clear. |
| 6 | XFDF | (PDF 1.4) shall be used only if the SubmitPDF flags are clear. If set, field names and values shall be submitted as XFDF. |
| 7 | IncludeAppendSaves | (PDF 1.4) shall be used only when the form is being submitted in Forms Data Format (that is, when both the XFDF and ExportFormat flags are clear). If set, the submitted FDF file shall include the contents of all incremental updates to the underlying PDF document, as contained in the Differences entry in the FDF dictionary (see Table 243). If clear, the incremental updates shall not be included. |
| 8 | IncludeAnnotations | (PDF 1.4) shall be used only when the form is being submitted in Forms Data Format (that is, when both the XFDF and ExportFormat flags are clear). If set, the submitted FDF file shall include includes all markup annotations in the underlying PDF document (see 12.5.6.2, 'Markup Annotations'). If clear, markup annotations shall not be included. |
| 9 | SubmitPDF | (PDF 1.4) If set, the document shall be 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 shall be ignored except GetMethod. |
| 10 | CanonicalFormat | (PDF 1.4) If set, any submitted field values representing dates shall be converted to the standard format described in 7.9.4, 'Dates.' NOTE 1 The interpretation of a form field as a date is not specified explicitly in the field itself but only in the JavaScript code that processes it. |
Table 237 - Flags for submit-form actions (continued)
| Bit position | Name | Meaning |
|---|---|---|
| 11 | ExclNonUserAnnots | (PDF 1.4) shall be used 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 shall include only those markup annotations whose T entry (see Table 170) matches the name of the current user, as determined by the remote server to which the form is being submitted. NOTE 2 The T entry for markup annotations specifies the text label that is displayed in the title bar of the annotation's pop-up window and is assumed to represent the name of the user authoring the annotation. NOTE 3 This allows multiple users to collaborate in annotating a single remote PDF document |
| 12 | ExclFKey | (PDF 1.4) shall be used only when the form is being submitted in Forms Data Format (that is, when both the XFDF and ExportFormat flags are clear). If set, the submitted FDF shall exclude the F entry. |
| 14 | EmbedForm | (PDF 1.5) shall be used only when the form is being submitted in Forms Data Format (that is, when both the XFDF and ExportFormat flags are clear). If set, the F entry of the submitted FDF shall be 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 shall be defined by the Fields array in the action dictionary (Table 236) together with the Include/Exclude and IncludeNoValueFields flags in the Flags entry (Table 237). Each element of the Fields array shall identify an interactive form field, either by an indirect reference to its field dictionary or (PDF 1.3) by its fully qualified field name (see 12.7.3.2, 'Field Names'). 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 shall consist of all fields in the document's interactive form except those listed in the Fields array.
The NoExport flag in the field dictionary's Ff entry (see Table 220 and Table 221) takes precedence over the action's Fields array and Include/Exclude flag. Fields whose NoExport flag is set shall not be included in a submit-form action.
Field names and values may be submitted in any of the following formats, depending on the settings of the action's ExportFormat, SubmitPDF, and XFDF flags (see the Bibliography for references):
Navigation: PDF-Spec-12-Actions | PDF-Spec-Index | PDF-Spec-12-Signatures