formfield

formfield

The FormField object, a legacy Word form field.

FormField

FormField(fldChar: CT_FldChar, parent: ProvidesStoryPart)

Bases: StoryChild

A legacy form field — a text input, check box or drop-down.

Word writes a form field as a complex field: a "begin" field-character carrying the field properties in w:ffData, the field instruction, a "separate" field-character, the current value, and an "end" field-character, each in its own run. This object proxies the "begin" field-character and reaches the rest through it.

Legacy form fields are what Word's Developer ribbon calls "Legacy Forms". They are distinct from content controls (w:sdt), which ContentControl covers.

The whole field is expected to sit in one paragraph, which is how Word writes a legacy form field — it does not let a paragraph break be typed into one. Reading or writing value on a field whose "end" field-character is in a later paragraph raises InvalidXmlError rather than returning a partial value.

Source code in src/docx/formfield.py

def __init__(self, fldChar: CT_FldChar, parent: t.ProvidesStoryPart):
    super().__init__(parent)
    self._element = self._fldChar = fldChar

calc_on_exit property writable

calc_on_exit: bool | None

Whether Word recalculates its fields when this one is left.

None when the document does not say, which Word treats as False.

default property writable

default: str | bool | None

The value this field starts out holding, None when it has no default.

A bool for a check box, the text for a text input, and the selected entry for a drop-down, matching value. Assigning an entry a drop-down does not offer raises ValueError, as it does for value; assigning None removes the default.

enabled property writable

enabled: bool | None

Whether the field can be edited.

None when the document does not say, which Word treats as enabled.

help_text property writable

help_text: str | None

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

items property

items: tuple[str, ...]

The entries of a drop-down field, in the order Word lists them.

Empty for a field that is not a drop-down.

max_length property writable

max_length: int | None

The most characters a text field accepts, None when unlimited.

None for a field that is not a text input.

name property writable

name: str | None

The bookmark name Word knows this field by, or None when it has none.

This is the name shown in the "Bookmark" box of the form-field properties dialog and the one a REF field or a macro would use.

status_text property writable

status_text: str | None

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

text_type property writable

text_type: WD_TEXT_FORM_FIELD_TYPE | None

Member of WdTextFormFieldType a text field accepts, or None.

None both for a field that is not a text input and for a text input that does not say, which Word treats as REGULAR_TEXT.

type property

type: WD_FORM_FIELD_TYPE

Member of WdFormFieldType telling what kind of field this is.

value property writable

value: str | bool

The value this field currently holds.

A bool for a check box; for a drop-down the selected entry, the empty string when nothing is selected; for a text input the result text Word last rendered, which is the empty string for an empty field.

Note that Word renders an empty text field as five spaces or similar filler text; that filler is what this returns, because it is what the document contains. Compare against default to tell an untouched field apart.

iter_form_fields

iter_form_fields(
    element: _Element, parent: ProvidesStoryPart
) -> Iterator[FormField]

Generate a FormField for each legacy form field in the subtree of element.

Source code in src/docx/formfield.py

def iter_form_fields(element: _Element, parent: t.ProvidesStoryPart) -> Iterator[FormField]:
    """Generate a |FormField| for each legacy form field in the subtree of `element`."""
    for fldChar in cast("List[CT_FldChar]", element.xpath(_FORM_FIELD_XPATH)):
        yield FormField(fldChar, parent)