form

form

Custom element classes for the legacy form-field elements.

A legacy form field — FORMTEXT, FORMCHECKBOX or FORMDROPDOWN — is a complex field spread across sibling runs:

<w:r><w:fldChar w:fldCharType="begin"><w:ffData>…</w:ffData></w:fldChar></w:r>
<w:r><w:instrText xml:space="preserve"> FORMTEXT </w:instrText></w:r>
<w:r><w:fldChar w:fldCharType="separate"/></w:r>
<w:r><w:t>the current value</w:t></w:r>
<w:r><w:fldChar w:fldCharType="end"/></w:r>

The properties of the field live in w:ffData on the "begin" w:fldChar; the value of a text field is the run content between "separate" and "end".

Only the container elements get element classes here. The leaf children of w:ffData and its type-specific children are read and written through their w:val attribute instead, because their tag names are reused elsewhere in the schema with other types — w:name is a style name, w:type is a section-break type, and w:default is three different types depending on which of w:textInput, w:checkBox and w:ddList it appears in. lxml resolves an element class by tag name alone, so registering any of them would silently change the type of an unrelated element.

CT_FFCheckBox

Bases: BaseOxmlElement

w:checkBox element, the check-box specifics of a form field.

checked property writable

checked: bool | None

Whether the box is currently ticked, or None when unspecified.

default property writable

default: bool | None

Whether the box starts out ticked, or None when unspecified.

CT_FFDDList

Bases: BaseOxmlElement

w:ddList element, the drop-down specifics of a form field.

default property writable

default: int | None

Index of the entry selected initially, or None when unspecified.

listEntry_vals property

listEntry_vals: List[str]

The w:val of each w:listEntry child, in document order.

A w:listEntry without a w:val contributes an empty string, which is what Word shows for it.

result property writable

result: int | None

Index of the entry currently selected, or None when unspecified.

CT_FFTextInput

Bases: BaseOxmlElement

w:textInput element, the text-input specifics of a form field.

default property writable

default: str | None

The text the field starts out holding, or None when unspecified.

format property writable

format: str | None

Word's formatting string for the value, e.g. "UPPERCASE", or None.

maxLength property writable

maxLength: int | None

The most characters the field accepts, or None when unlimited.

type property writable

type: WD_TEXT_FORM_FIELD_TYPE | None

Member of WdTextFormFieldType, or None when unspecified.

Word treats an unspecified type as REGULAR.

CT_FFData

Bases: BaseOxmlElement

w:ffData element, the properties of a legacy form field.

Its schema type is an unbounded xsd:choice, not a sequence, so its children have no required order and no successors bookkeeping applies.

calcOnExit property writable

calcOnExit: bool | None

Whether Word recalculates fields when this one is left, or None.

enabled property writable

enabled: bool | None

Whether the field can be edited, or None when unspecified.

Word treats an unspecified value as enabled.

helpText property writable

helpText: str | None

The text Word shows when F1 is pressed in the field, or None.

name property writable

name: str | None

The bookmark name of the field, or None when it has none.

statusText property writable

statusText: str | None

The text Word shows in the status bar for the field, or None.

CT_FldChar

Bases: BaseOxmlElement

w:fldChar element, a field-character marking a boundary of a complex field.

r property

r: _Element | None

The w:r element this field-character belongs to, or None.

A w:fldChar is always a child of a run in a valid document, but a caller can detach one.

CT_SimpleField

Bases: BaseOxmlElement

w:fldSimple element, a field whose instruction and result are one element.

The instruction is an attribute and the cached result is the element's content, so unlike a complex field this is self-contained. Word writes a legacy form field as a complex field rather than a simple one, and w:ffData is not allowed here.

result_text property

result_text: str

The result text of this field, as Word last rendered it.

text property

text: str

The text this field displays, which is its cached result.