Query a form field (GetField)

Objective

Get the current value of a single form field within a PDF document (for example, a text box or a checkbox), identified by its name.

Parameters

Result

The field's value, the field's possible values (see below), and the operation status (Error / ErrorMessage) via PDFToolsStatus (the result is exposed as PDFToolsFormField). Both are empty if the operation fails (see below).

Functional details

• A non-existent field is an error: if the indicated name does not exist in the document, the operation fails and an empty value/possible values are returned.

• Case-sensitive: the field name (for example Country vs. country) is case-sensitive. If the indicated name does not exactly match the one defined in the document, it is treated as a non-existent field.

• Field's possible values: in addition to the current value, it reports which values the field accepts, as a list of comma-separated texts, in order to know beforehand what can be sent (and validate it) when filling the field with SetField. This only applies to fields with a closed set of valid values:

• Checkbox / radio button: the names of each possible state (for example Off,Yes for a simple checkbox, or Off,F,O,M for a group of mutually exclusive options). Off is always the standard value for "unchecked/off"; the rest of the names are defined by whoever designed the form in the PDF.

• List/combo box: the values that must actually be sent when filling the field (not the visible labels the user sees expanded in the PDF — for example, the visible label might be "Argentina" but the value to send might be AR).

• Text field (and any other type without a closed set of values): empty, since it accepts any text.

• There is no native "date" type: the PDF forms standard only defines four field types: text, checkbox/radio button, list/combo, and signature. What often looks like a "date field" with a calendar picker in tools like Adobe Acrobat is actually a plain text field with JavaScript embedded in the document itself; this component treats any field of this kind as plain text, without validating or interpreting date formats.

• The source file cannot be password-protected.

Usage example

 &PDFFileSource      = "C:\Documents\form.pdf"
 &PDFToolsFieldKey  = "Country"

 &PDFToolsStatus = &PdfToolsUtils.GetField(&PDFFileSource,&PDFToolsFieldKey,&PDFToolsFormField)

 // Possible result (&PDFToolsFormField.Key/.Value/.Options):

//| Key     | Value | Options          |
//|---------|-------|------------------|
//| Country |  AR   | "AR,BR,UY,CL"    |

Error and warning messages