Legacy Form Fields

Aspose.Words FOSS for .NET reads and manipulates Word’s legacy (pre-content-control) form fields — text input, checkbox, and drop-down fields — through the FormField class and its three specialized field subclasses in Aspose.Words.Fields.

Reading Form Field Values

Document.Range.FormFields (a FormFieldCollection) gives direct access to every legacy form field in a range without walking the node tree manually. Each FormField exposes Name (the bookmark-style identifier used to reference the field), Type (a FieldType value identifying which kind of form field it is), Result (the current value), Enabled, and help/status text via HelpText/OwnHelp and StatusText/OwnStatus. SetTextInputValue(newValue) sets a new value for a text input field directly. Index into FormFieldCollection by bookmark name (e.g. formFields["BookmarkName"]) to retrieve a specific field, and Remove(formField) / RemoveAt(index) delete fields from the collection.

Text, Checkbox, and Drop-Down Field Types

The three legacy form field types each have a dedicated class: FieldFormText (the FORMTEXT field, corresponding to FieldType.FieldFormTextInput) for free-text input, FieldFormCheckBox (the FORMCHECKBOX field) for a boolean toggle, and FieldFormDropDown (the FORMDROPDOWN field) for a selection list. On the underlying FormField node, TextInputType (a TextFormFieldType value — Regular, Number, Date, CurrentDate, CurrentTime, or Calculated) and TextInputFormat control how a text field’s value is interpreted and formatted; MaxLength bounds its input length; TextInputDefault supplies its default value. Checked and Default apply to checkbox fields, with IsCheckBoxExactSize/CheckBoxSize controlling its rendered size. Drop-down fields carry their option list in DropDownItems, a DropDownItemCollection supporting Add, Insert, Remove, Contains, and IndexOf, plus DropDownSelectedIndex for the currently selected item.

Tips and Best Practices

Use Document.Range.FormFields rather than manually filtering Document.Range.Fields by type — it’s the direct, typed entry point for legacy form fields.
Set CalculateOnExit when a form field’s value should trigger dependent field recalculation as soon as the user leaves it.
FormField.EntryMacro / ExitMacro reference VBA macro names configured in the original document — reading them does not execute any macro code.
Check TextInputType before parsing a text field’s Result as a number or date — Regular fields impose no format constraint.

Common Issues

Issue	Cause	Fix
Indexing `FormFieldCollection` by bookmark name returns null	Form field’s bookmark name doesn’t match, or the field doesn’t exist in the searched range	Confirm the exact bookmark name via `FormField.Name` while enumerating
Checkbox state not reflected after setting `Checked`	Document not saved after modification	Save the document after modification; `Checked` is read on next access
Drop-down `DropDownSelectedIndex` out of range	Index doesn’t correspond to an item in `DropDownItems`	Validate the index against `DropDownItems.Count` before setting
Text field value not applied	Used direct property assignment instead of `SetTextInputValue`	Call `SetTextInputValue(newValue)` on the `FormField`

FAQ

What’s the difference between `FormField` and `FieldFormText`/`FieldFormCheckBox`/`FieldFormDropDown`?

FormField is the generic node representing any legacy form field, reached through Document.Range.FormFields. FieldFormText, FieldFormCheckBox, and FieldFormDropDown are the field-specific classes (deriving from Field) for each field type when working through the general Field collection instead.

How do I get all form field values in a document?

Enumerate Document.Range.FormFields and read Name/Result on each FormField.

Can I add options to a drop-down form field?

Yes — FormField.DropDownItems is a DropDownItemCollection with Add(value), Insert(index, value), and Remove(name).

Are these the same as modern content controls?

No. Legacy form fields (FORMTEXT, FORMCHECKBOX, FORMDROPDOWN) predate Word’s structured document tag (content control) model; both can appear in the same document.

API Reference Summary

Class / Method	Description
`Document.Range.FormFields`	Direct access to all legacy form fields in a range
`FormField`	Generic legacy form field node: name, type, result, enabled state
`FormFieldCollection`	Collection of `FormField` objects; indexer by bookmark name, `Remove()`
`FieldFormText`	`FORMTEXT` field class
`FieldFormCheckBox`	`FORMCHECKBOX` field class
`FieldFormDropDown`	`FORMDROPDOWN` field class
`TextFormFieldType`	Enum for text field input format (`Regular`, `Number`, `Date`, etc.)
`DropDownItemCollection`	Editable list of a drop-down field’s options

Legacy Form Fields