API reference / Common / Engine types / TextControlBlock

Interface: TextControlBlock

A block-level structured document tag / content control (docx w:sdt, CT_SdtBlock) — a container of nested blocks, contributing no characters of its own.

Its blocks live in the parent story's offset space, which the offset walk recurses into: a selection may start outside the control and end inside it, which is what Word does and what a nested story would forbid. What the control is rides in control, shared with every other level; this type says only that the level is block.

The extent is not in the text. A control wraps a range rather than occupying one, so the CRDT carries it as a mark over the characters its blocks realize, keyed by the control's own ContentControlId — and decode rebuilds this container from that range. Nothing of the control is written into the offset space, which is what lets one be formed, dissolved or regrouped without a character moving: a merge that leaves the range ending mid-paragraph is repaired by rewriting the mark, where two bracket characters would have left a state no legal tree could express.

A block-level range must cover whole blocks, so decode snaps it to block boundaries. The span level is TextControlSpan — the same construct and the same carrier one level below, where the range must instead lie inside a single paragraph.

See Text Model.

Properties

Property	Description
control ContentControl	w:sdtPr + w:sdtEndPr — what the control is: kind, tag, alias, lock, binding, placeholder.
blocks? TextBlock[]	w:sdtContent (CT_SdtContentBlock) — the blocks it wraps, in the parent story's offset space. Never empty. The extent rides a mark over these blocks' characters and a mark cannot hold an empty range, so a control with no content cannot be encoded at all: import gives an empty w:sdtContent a paragraph, and a delete that would empty a control restores its placeholder instead — Word's own spelling of an "empty" control. [TextBlock] is already the right child type: CT_SdtContentBlock's members are w:p, w:tbl, a nested w:sdt, w:customXml and math, which is this enum's variant set — plus the revision containers, whose loose runs import as a paragraph. The one over-permission is w:altChunk, which lives in EG_BlockLevelElts and not EG_ContentBlockContent and so is illegal here — a constraint the flat enum cannot state, as [TextBlock] notes.