Skip to content

Technique PDF12:Providing name, role, value information for form fields in PDF documents

Applicability

Tagged PDF documents with interactive form fields.

This technique relates to:

Description

The objective of this technique is to ensure that assistive technologies can gather information about and interact with form controls in PDF content.

The types of PDF form controls are: text input field, check box, radio button, combo box, list box, and button.

Providing name, role, state, and value information for all form components enables compatibility with assistive technology, such as screen readers, screen magnifiers, and speech recognition software used by people with disabilities.

Interactive Form Dictionary Entries Used to Define Comments
FT Role Controls that share field type also use field flags to set the appropriate role. In Adobe Acrobat the role for form controls is set automatically.
TU Name In Adobe Acrobat the TU entry value is provided via the Tooltip field in the form control's Properties dialog. This should not be confused with the T entry which is defined as the Name in Acrobat's form control properties dialog - the name field in the Properties dialog is not used to provide the name for a control when read by assistive technologies.
CA Name (Pushbuttons only) In Adobe Acrobat the CA entry value is provided via the label field in the form control's Properties dialog.
V Value The Value entry is set by the user interacting with the control, where a value is needed.
DV Default Value In Adobe Acrobat the DV entry value can be set in the form control's Properties dialog.

The following table describes how the role, name, value, and state are defined for PDF form controls created using Adobe Acrobat Pro. Adobe LiveCycle Designer provides the same controls as well as several additional ones: see Example 2 below.

PDF form element Role (FT entry) Name (TU entry) Value (V entry) Configurable States
Text field Text /Tx Tooltip Default value (DV entry in field dictionary) can be set in the Properties dialog. Value is entered by user. Read Only, Required, Multiline, Password
Check box Check box /Btn Tooltip V entry is set to 'Yes' or 'No' depending on Checked state. Read Only, Required, Checked
Radio button Radio button /Btn (Field Flag set to 'Radio') Tooltip V entry is set to 'Yes' or 'No' depending on Checked state. Read Only, Required, Checked
Combo box Combo box /Ch (Field Flag set to 'Combo') Tooltip Default value (/DV) can be set in the Properties dialog. Value is determined by user selection. Read Only, Required
List box Drop-down list /Ch Tooltip Default value (/DV) can be set in the Properties dialog. Value is determined by user selection. Read Only, Required
Button Push button /Btn (Field Flag set to 'Pushbutton') Label (CA entry instead of TU entry) Push buttons do not have or require a value. Read Only, Required
Signature field Text /Sig Tooltip Default value (DV entry in field dictionary) can be set in the Properties dialog. Value is entered by user. Read Only, Required

Examples

Example 1: Specifying name, role, value and/or state for a form field using Adobe Acrobat Pro

This example is shown with Adobe Acrobat Pro. There are other software tools that perform similar functions.

This example uses a check box for illustration; the procedure is the same for other form controls.

  1. Open the Prepare Form tool.
  2. Select the form field you are creating or modifying and access the context menu for it.
  3. Select the Properties... option.
  4. Specify the name by adding a value to the Tooltip field. This will used by the accessibility API as the Name for the control. To conform to the Label In Name Criterion, the Tooltip value must contain the text that presented visually.
  5. If you need to specify the default value and state, select the Options tab for these options.

The image below shows the Check Box Properties dialog, open in the General tab. (The Name field in the dialog is not needed for accessibility.)

General tab on the Check Box Properties dialog, showing name and tool tip fields for a check box

This example is shown in operation in the working example of specifying name, role, value using Acrobat Pro.

Example 2: Adding a checkbox in a PDF document using the /Btn field type

The following code fragment illustrates code that is typical for a simple check box field such as shown in Examples 1 and 2. This is typically accomplished by an authoring tool. 

1 0 obj
  << /FT /Btn     % Role
     /TU Retiree  % Name
     /V /Yes      % Value
     /AS /Yes
     /AP << /N << /Yes 2 0 R /Off 3 0 R>>
  >>
endobj

Other sources

No endorsement implied.

Tests

Procedure

  1. For the form control, verify that name, role, and value/state are specified by one of the following:

    • Use a screen reader to navigate to the form control and check that it can be activated or that its value can be changed. Verify that the name (tooltip) and role are announced.
    • Use a tool capable of showing the form field information to open the PDF document and verify that the form control has the correct name, role, value, and state (if appropriate) information.
    • Use a tool that exposes the document through the accessibility API, and verify that the form control has the correct name, role, value, and state (if appropriate) information.

Expected Results

  • #1 is true.
Back to Top