0
# Interactive Forms
1

2
Comprehensive support for PDF interactive forms (AcroForms) including text fields, checkboxes, radio buttons, choice lists, and form submission with full form manipulation capabilities.
3

4
## Form Access and Management
5

6
Access and manipulate PDF forms and their fields.
7

8
```java { .api }
9
// Form access methods in org.apache.pdfbox.pdmodel.PDDocument
10
public PDAcroForm getAcroForm();
11
public void setAcroForm(PDAcroForm acroForm);
12

13
// Form management methods in org.apache.pdfbox.pdmodel.interactive.form.PDAcroForm
14
public PDAcroForm(PDDocument document);
15
public PDAcroForm(PDDocument document, COSDictionary form);
16

17
public List<PDField> getFields();
18
public PDField getField(String fullyQualifiedName);
19
public void setFields(List<PDField> fields);
20
public void flatten() throws IOException;
21
public void refreshAppearances() throws IOException;
22
```
23

24
## Field Operations
25

26
Common operations available for all form field types.
27

28
```java { .api }
29
// Base field methods in org.apache.pdfbox.pdmodel.interactive.form.PDField
30
public String getPartialName();
31
public void setPartialName(String partialName);
32
public String getFullyQualifiedName();
33
public String getMappingName();
34
public void setMappingName(String mappingName);
35
public String getAlternateFieldName();
36
public void setAlternateFieldName(String alternateFieldName);
37

38
// Field value operations
39
public String getValue();
40
public void setValue(String value) throws IOException;
41
public String getDefaultValue();
42
public void setDefaultValue(String defaultValue);
43

44
// Field properties
45
public boolean isReadOnly();
46
public void setReadOnly(boolean readOnly);
47
public boolean isRequired();
48
public void setRequired(boolean required);
49
public boolean isNoExport();
50
public void setNoExport(boolean noExport);
51

52
// Widget annotations
53
public List<PDAnnotationWidget> getWidgets();
54
public void setWidgets(List<PDAnnotationWidget> widgets);
55
```
56

57
## Text Fields
58

59
Handle single-line and multi-line text input fields.
60

61
```java { .api }
62
// Constructor and methods in org.apache.pdfbox.pdmodel.interactive.form.PDTextField
63
public PDTextField(PDAcroForm acroForm);
64
public PDTextField(PDAcroForm acroForm, COSDictionary field, PDField parent);
65

66
// Text field specific properties
67
public boolean isMultiline();
68
public void setMultiline(boolean multiline);
69
public boolean isPassword();
70
public void setPassword(boolean password);
71
public boolean isFileSelect();
72
public void setFileSelect(boolean fileSelect);
73
public boolean isDoNotSpellCheck();
74
public void setDoNotSpellCheck(boolean doNotSpellCheck);
75
public boolean isDoNotScroll();
76
public void setDoNotScroll(boolean doNotScroll);
77

78
// Text formatting
79
public int getMaxLength();
80
public void setMaxLength(int maxLength);
81
public String getDefaultAppearance();
82
public void setDefaultAppearance(String defaultAppearance);
83
```
84

85
## Checkboxes
86

87
Handle checkbox form fields with on/off states.
88

89
```java { .api }
90
// Constructor and methods in org.apache.pdfbox.pdmodel.interactive.form.PDCheckBox
91
public PDCheckBox(PDAcroForm acroForm);
92
public PDCheckBox(PDAcroForm acroForm, COSDictionary field, PDField parent);
93

94
// Checkbox state management
95
public void check() throws IOException;
96
public void unCheck() throws IOException;
97
public boolean isChecked();
98
public String getOnValue();
99
public String getOffValue();
100
public void setValue(String value) throws IOException;
101
```
102

103
## Radio Buttons
104

105
Handle radio button groups with multiple options.
106

107
```java { .api }
108
// Constructor and methods in org.apache.pdfbox.pdmodel.interactive.form.PDRadioButton
109
public PDRadioButton(PDAcroForm acroForm);
110
public PDRadioButton(PDAcroForm acroForm, COSDictionary field, PDField parent);
111

112
// Radio button operations
113
public List<String> getExportValues();
114
public String getSelectedExportValue();
115
public void setValue(String value) throws IOException;
116
public List<PDCheckBox> getKids();
117
```
118

119
## Choice Fields (Lists and Dropdowns)
120

121
Handle list boxes and dropdown/combo boxes.
122

123
```java { .api }
124
// Constructor and methods in org.apache.pdfbox.pdmodel.interactive.form.PDChoice
125
public PDChoice(PDAcroForm acroForm);
126
public PDChoice(PDAcroForm acroForm, COSDictionary field, PDField parent);
127

128
// Choice options management
129
public List<String> getOptions();
130
public void setOptions(List<String> options);
131
public List<String> getOptionsExportValues();
132
public void setOptionsExportValues(List<String> optionsExportValues);
133
public List<String> getOptionsDisplayValues();
134
public void setOptionsDisplayValues(List<String> optionsDisplayValues);
135

136
// Selection operations
137
public List<Integer> getSelectedOptionsIndex();
138
public void setSelectedOptionsIndex(List<Integer> selectedOptionsIndex);
139
public List<String> getValue();
140
public void setValue(List<String> value) throws IOException;
141

142
// Choice field properties
143
public boolean isCombo();
144
public void setCombo(boolean combo);
145
public boolean isEdit();
146
public void setEdit(boolean edit);
147
public boolean isSort();
148
public void setSort(boolean sort);
149
public boolean isMultiSelect();
150
public void setMultiSelect(boolean multiSelect);
151
public boolean isDoNotSpellCheck();
152
public void setDoNotSpellCheck(boolean doNotSpellCheck);
153
```
154

155
## List Boxes
156

157
Specialized choice field for list display.
158

159
```java { .api }
160
// Constructor in org.apache.pdfbox.pdmodel.interactive.form.PDListBox
161
public PDListBox(PDAcroForm acroForm);
162
public PDListBox(PDAcroForm acroForm, COSDictionary field, PDField parent);
163

164
// List-specific properties inherited from PDChoice
165
public int getTopIndex();
166
public void setTopIndex(int topIndex);
167
```
168

169
## Combo Boxes
170

171
Specialized choice field for dropdown/combo display.
172

173
```java { .api }
174
// Constructor in org.apache.pdfbox.pdmodel.interactive.form.PDComboBox
175
public PDComboBox(PDAcroForm acroForm);
176
public PDComboBox(PDAcroForm acroForm, COSDictionary field, PDField parent);
177

178
// Combo-specific operations inherited from PDChoice
179
// Additional combo-specific behavior through base class methods
180
```
181

182
## Signature Fields
183

184
Handle digital signature fields in forms.
185

186
```java { .api }
187
// Constructor and methods in org.apache.pdfbox.pdmodel.interactive.form.PDSignatureField
188
public PDSignatureField(PDAcroForm acroForm);
189
public PDSignatureField(PDAcroForm acroForm, COSDictionary field, PDField parent);
190

191
// Signature operations
192
public PDSignature getSignature();
193
public void setSignature(PDSignature signature);
194
public byte[] getSignedByteRange() throws IOException;
195
```
196

197
## Usage Examples
198

199
### Accessing and Reading Form Fields
200

201
```java
202
PDDocument document = Loader.loadPDF(new File("form.pdf"));
203
PDAcroForm acroForm = document.getAcroForm();
204

205
if (acroForm != null) {
206
    // Get all fields
207
    List<PDField> fields = acroForm.getFields();
208
    
209
    for (PDField field : fields) {
210
        System.out.println("Field name: " + field.getFullyQualifiedName());
211
        System.out.println("Field value: " + field.getValue());
212
        System.out.println("Field type: " + field.getClass().getSimpleName());
213
    }
214
    
215
    // Get specific field
216
    PDField nameField = acroForm.getField("Name");
217
    if (nameField != null) {
218
        System.out.println("Name field value: " + nameField.getValue());
219
    }
220
}
221

222
document.close();
223
```
224

225
### Filling Form Fields
226

227
```java
228
PDDocument document = Loader.loadPDF(new File("form.pdf"));
229
PDAcroForm acroForm = document.getAcroForm();
230

231
if (acroForm != null) {
232
    // Fill text field
233
    PDTextField nameField = (PDTextField) acroForm.getField("Name");
234
    nameField.setValue("John Doe");
235
    
236
    // Fill checkbox
237
    PDCheckBox agreeField = (PDCheckBox) acroForm.getField("Agree");
238
    agreeField.check();
239
    
240
    // Fill radio button
241
    PDRadioButton genderField = (PDRadioButton) acroForm.getField("Gender");
242
    genderField.setValue("Male");
243
    
244
    // Fill choice field (dropdown)
245
    PDChoice countryField = (PDChoice) acroForm.getField("Country");
246
    countryField.setValue(Arrays.asList("USA"));
247
    
248
    // Refresh form appearance
249
    acroForm.refreshAppearances();
250
}
251

252
document.save("filled-form.pdf");
253
document.close();
254
```
255

256
### Creating Form Fields
257

258
```java
259
PDDocument document = new PDDocument();
260
PDPage page = new PDPage(PDRectangle.A4);
261
document.addPage(page);
262

263
PDAcroForm acroForm = new PDAcroForm(document);
264
document.setAcroForm(acroForm);
265

266
// Create text field
267
PDTextField textField = new PDTextField(acroForm);
268
textField.setPartialName("Name");
269
textField.setDefaultValue("Enter your name");
270

271
// Create text field widget
272
PDAnnotationWidget textWidget = new PDAnnotationWidget();
273
textWidget.setRectangle(new PDRectangle(100, 700, 200, 20));
274
textWidget.setPage(page);
275
page.getAnnotations().add(textWidget);
276
textField.getWidgets().add(textWidget);
277

278
// Create checkbox
279
PDCheckBox checkBox = new PDCheckBox(acroForm);
280
checkBox.setPartialName("Subscribe");
281

282
PDAnnotationWidget checkWidget = new PDAnnotationWidget();
283
checkWidget.setRectangle(new PDRectangle(100, 650, 20, 20));
284
checkWidget.setPage(page);
285
page.getAnnotations().add(checkWidget);
286
checkBox.getWidgets().add(checkWidget);
287

288
// Add fields to form
289
acroForm.setFields(Arrays.asList(textField, checkBox));
290

291
document.save("new-form.pdf");
292
document.close();
293
```
294

295
### Working with Choice Fields
296

297
```java
298
PDDocument document = Loader.loadPDF(new File("form.pdf"));
299
PDAcroForm acroForm = document.getAcroForm();
300

301
// Get combo box field
302
PDComboBox comboBox = (PDComboBox) acroForm.getField("Country");
303
if (comboBox != null) {
304
    // Set options
305
    List<String> options = Arrays.asList("USA", "Canada", "Mexico", "UK", "Germany");
306
    comboBox.setOptions(options);
307
    
308
    // Set default selection
309
    comboBox.setValue(Arrays.asList("USA"));
310
    
311
    // Configure properties
312
    comboBox.setEdit(true);  // Allow custom text entry
313
    comboBox.setSort(true);  // Sort options alphabetically
314
}
315

316
// Get list box field
317
PDListBox listBox = (PDListBox) acroForm.getField("Languages");
318
if (listBox != null) {
319
    // Set multiple options with export values
320
    List<String> displayValues = Arrays.asList("English", "Spanish", "French", "German");
321
    List<String> exportValues = Arrays.asList("en", "es", "fr", "de");
322
    
323
    listBox.setOptionsDisplayValues(displayValues);
324
    listBox.setOptionsExportValues(exportValues);
325
    listBox.setMultiSelect(true);
326
    
327
    // Select multiple values
328
    listBox.setValue(Arrays.asList("en", "es"));
329
}
330

331
acroForm.refreshAppearances();
332
document.save("updated-form.pdf");
333
document.close();
334
```
335

336
### Form Flattening
337

338
```java
339
PDDocument document = Loader.loadPDF(new File("filled-form.pdf"));
340
PDAcroForm acroForm = document.getAcroForm();
341

342
if (acroForm != null) {
343
    // Flatten the form (convert fields to static content)
344
    acroForm.flatten();
345
    
346
    // Form is now non-interactive but retains visual appearance
347
}
348

349
document.save("flattened-form.pdf");
350
document.close();
351
```