Widgets

Widget Level vs Field Level Properties and Events

What are Widgets in the Context of PDF Form Fields?

Widgets are "children" of a field. In other words, they are copies of the same field. Suppose you create a text field called Text and copy it four times for a total of 5 fields. You will notice the following field names in the field panel in form editing mode:

Text#0
Text#1
Text#2
Text#3
Text#4  

These names are not the actual field names. They are display names in the panel to signify they are widgets of the field named Text. If you try to call a field with the #-extension like this you will get a null error:

this.getField("Text#1");

The order of the #-extension numbers are the order in which they were created. If you delete any of these fields, some will be renamed in the panel so you always end up with #-extension fields from 0 to the number of fields, minus 1. To call individual widgets with a script, add a period and a number to end of the names, starting with 0 for the the original field, and 1 through the last #-extension number for the remainder. For example:

Panel Display Names          Widget Field Names in JavaScript
               Text#0                                              Text.0
               Text#1                                              Text.1
               Text#2                                              Text.2
               Text#3                                              Text.3
               Text#4                                              Text.4

Field Level Properties and Events

Some field properties apply at the field level, meaning there can be only one for all widgets of that field. The value property of a text field is an example.

Suppose you have 10 text fields in the document, all called First Name. That means there are 10 widgets of the First Name field object. There can only be one value for this field. If you enter the name "John" into any of the the widgets of the First Name field, it will flow through to all widgets. If you change the John value to something else in any of the widgets, it will automatically change in all of them. Those new to Acrobat sometimes think this is a glitch, but it is actually a feature that can be used to the form designer’s advantage when requiring field data to flow through the document after being entered only once.

Format is an event that applies at the field level. There can only be one format for all widgets of the field. The other events that apply at the field level are Keystroke, Validate, and Calculate. When you open the field properties of one text field you will notice the tabs Calculate, Validate, and Format (Keystroke is in the Format tab).

PDF Text Field Property Tabs With One Field Selected

When setting or changing these field level properties or events manually (i.e. without a script), they must be changed individually for each field. In other words, if you select multiple fields and try to change any of those properties or events, the previously mentioned tabs will be missing.

PDF Text Field Property Tabs With Multiple Fields Selected

This is not an issue with multiple widgets of the same field because if the property or event is changed in one widget it is changed in all widgets. In this article I demonstrated how to change field events using JavaScript.

Widget Level Properties and Events

Properties and events that apply at the widget level can be different for each widget. Most of these properties are field appearance properties like fill color, text font, text size, text color, visibility, etc.

Widget level events are MouseUp, MouseDown, MouseEnter, MouseExit, OnFocus, and OnBlur. The Acrobat JavaScript reference guide contains a list of field properties and events for field level and widget level.

Setting Properties and Events With JavaScript

Since there can only be one field level property or field level event for all widgets of a field, when setting these properties or events with JavaScript, you can call either the main field, or any of the widgets. Back to the example of five widgets of the field Text, to set the value you could use the field name Text, or any of Text.0 through Text.4 names. The result would be the same. The property or event would change for all widgets. Any of these would change the value of Text and all its widgets to ABC:

this.getField("Text").value="ABC";
this.getField("Text.0").value="ABC";
this.getField("Text.1").value="ABC";
this.getField("Text.2").value="ABC";
this.getField("Text.3").value="ABC";
this.getField("Text.4").value="ABC";

For widget level properties, using the parent field name will change the property for all widgets:

this.getField("Text").fillColor=color.yellow;

To change the property for individual widgets, use the number suffixes like this:

this.getField("Text.0").fillColor=color.yellow;
this.getField("Text.1").fillColor=color.red;
this.getField("Text.2").fillColor=color.green;
this.getField("Text.3").fillColor=color.blue;
this.getField("Text.4").fillColor=color.cyan;