API reference / Common / Engine types / TextComplexField

Interface: TextComplexField

A field spelled with a field code: w:fldChar+w:instrText, or w:fldSimple.

The definition alone. Where it sits is said by the two marks that carry it — [TextComplexFieldStart] and [TextComplexFieldEnd] — between which the result is ordinary content in the parent's offset space, not a container and not a space of its own.

w:fldChar means field character: three control codes carried over from the binary format, each one character of the text stream. So two one-unit marks are not an approximation of the encoding, they are it — which is why this system is not levelled into block and span containers the way the content control is, and why a straddling field needs no escape hatch.

w:fldSimple is a compact spelling of the same system rather than a system of its own: the strict subset that lives in one paragraph and needs no form. It imports to the same two marks.

The other field system is the self-contained-element one (TextSimpleField), and the two share no type — not a definition, not a kind. See Text Fields.

Properties

Property	Description
id string	Stable model id, carried by the opening mark alone.
kind TextComplexFieldKind	What the field is: the keyword at the head of its instruction.
instruction? string	The field code, verbatim: " PAGEREF _Toc491 \\h ". A String, not a parse, because a field code is code, not content: it has a grammar, it is not styled prose, and character-level co-editing over a syntax only produces broken intermediate states both peers then see. It is written whole, by a properties panel over ResolvedFieldParameters with a raw input beneath it, which is also the right co-editing granularity. A nested field is written { MERGEFIELD Country } here and expands to real marks on export — a scanner that must be quote-aware, or the literal braces in { IF { MERGEFIELD X } = "a{b}c" "y" "n" } are misread.
instructionProperties? TextCharacterProperties	The instruction's own character properties — the w:instrText run's that holds the first character of its keyword. Empty for a w:fldSimple, whose instruction is an attribute. What a value the field evaluates to paints with: not either mark's properties, and not the result's unless \* MERGEFORMAT keeps them, which is how Word paints a PAGE. The keyword's run rather than the first, because Word's is: an instruction opening with a space in one run and its keyword in the next paints in the next.
locked? boolean	w:fldLock — never recalculate this field.
dirty? boolean	w:dirty — the result is known stale, and the next update should replace it. Set by an edit inside the result, too.
data? string	w:fldData — an opaque, application-defined payload. A preservation slot: never interpreted, kept because data we cannot read is data we could never reconstruct after dropping it.
form? TextFormField	w:ffData — the form field's own state. The one payload here that is not preservation; see [TextFormField]. It belongs to this system alone: it rides a w:fldChar begin, which no other spelling has room for. FORMCHECKBOX and FORMDROPDOWN are result-less, so the checked flag, the entries and the selection live nowhere else. Boxed because almost no field is a form field, and this definition rides inside every opening mark.