Table of Contents

Namespace DocWright.Dom.Editing

Classes

BookmarkEditingExtensions

Finds bookmarks and edits the content they span.

BookmarkReference

A located bookmark: its two markers and the content they span.

The pair is what makes a bookmark editable. The markers are ordinary inlines, they need not sit in the same paragraph, and a bookmark whose markers are adjacent spans nothing at all — the degenerate case a naive "replace the content" implementation silently turns into a no-op or an exception.

BuiltInStyles

Word's definitions of its built-in styles, as Word for Microsoft 365 adds them to a document that uses one for the first time (read with tools/Probe-WordBuiltInStyles.ps1, WQ-0106): the headings, Title, Subtitle, the quotes, List Paragraph, No Spacing, Caption and the character styles of the Styles gallery. ApplyBuiltInStyle(WordDocument, DocumentSpan, string) applies one by name, adding it when the document has none of that name.

CaptionEditingExtensions

References > Insert Caption as an undoable edit, as Word writes it (WQ-0112, tools/Probe-WordCaptions.ps1): a paragraph in the Caption style holding the label, a SEQ field and the title, above or below the table or paragraph at the position; every caption of the label is numbered again.

CaptionOptions

Word's Insert Caption dialog.

CitationEditingExtensions

Phase 172 (WQ-0153): a document's sources, its citation style, citations and a bibliography, as Word's References

Citations & Bibliography edits them. The sources live in the document's b:Sources custom XML part (added, with its properties part and relationships, as Word adds it); a citation is a CITATION field in a citation content control; a bibliography is a BIBLIOGRAPHY field whose result is a paragraph per source. Each is one undo step.

ContentEditingExtensions

Fluent creation over the DOM primitives: every method appends one node to its natural host and returns the node it created, so calls chain.

Nothing is defaulted into a formatting bag. A paragraph appended here has an empty ParagraphFormat and its runs have no CharacterFormat at all unless one is supplied. That is not tidiness: the bags are sparse, null means "inherit from the style chain", and a helper that wrote a concrete default would both break inheritance and add markup to the saved package that the caller never asked for.

The DOM is not thread-safe and these methods do not make it so. One document is edited by one thread at a time.

CorePropertiesEditingExtensions

The document properties of docProps/core.xml, read and set as an edit (Word's File > Info, WQ-0124). The part rides through a load as a preserved part; these read it and rewrite it in place, so every element this model does not name (the revision, the dates, the last author, anything else) is kept as it was.

CoverPageDesign

One design of DocWright's cover page gallery (Phase 175): its name and how it lays out the fields. The designs are DocWright's own; Word's gallery is Microsoft's and is not reproduced.

CoverPageEditingExtensions

Insert > Cover Page as Word inserts one (Phase 175, WQ-0156): a gallery entry in a Cover Pages building-block content control at the start of the document, ending in a page break inside the control; another cover page replaces it; Remove Current Cover Page takes it away. One undo step each.

CoverPageGallery

DocWright's cover page gallery (Phase 175): a few plain designs, each in the document's theme.

CoveredParagraph

One paragraph of what a span covers (GetCoveredParagraphs(DocumentSpan)).

CoveredText

A piece of a text run a span covers (Text).

CrossReferenceEditingExtensions

Word's Insert > Cross-reference as an undoable edit (WQ-0111, tools/Probe-WordCrossReference.ps1): the headings, bookmarks and notes it offers, and a REF, PAGEREF or NOTEREF field to one, with Word's _Ref bookmark round a heading's text or a note's mark.

CrossReferenceTarget

What a cross-reference points at: a heading, a bookmark or a note.

DocumentEdit

The record of one text edit (TextEditingExtensions): where a caret was and goes, which paragraphs changed, and how to take the edit back exactly.

DocumentFragment

Formatted content to insert at a position: a standalone document holding the content and the definitions it uses (styles, lists, notes, media, link targets), and whether its last paragraph's mark is part of it. Made by ExtractFragment(WordDocument, DocumentSpan) (copy) or by FromDocument(WordDocument, bool) from a document any reader produced (HTML from a clipboard, a DOCX, RTF …). Owns its document.

DocumentMergeExtensions

Section-level merge and split.

Ownership. Everything the imported content needs is materialized during the call: image bytes are read into the destination, not referenced back into the source's package. The source document may be disposed immediately afterwards. If it has already been disposed, its media cannot be read and the merge fails with InvalidDocumentException rather than producing a document with empty pictures.

What is not carried across. A merge moves content, not the package. The destination keeps its own theme, settings and document defaults, and the source's opaque package parts — custom XML, document properties, embedded objects, the glossary — stay behind. Those describe a document, not the sections being imported, and there is no meaningful way to have two of them. COMPAT.md enumerates the loss.

DocumentProtectionEditingExtensions

The document's protection settings (w:documentProtection, w:writeProtection) changed as an edit (Phase 157, WQ-0130): what Word's Restrict Editing starts and stops.

DocumentRange

A contiguous span of sibling nodes — inlines inside one paragraph, or blocks inside one section, cell, header, footer or note — that can be copied, moved or deleted as a unit.

A range is a snapshot of positions, not a live cursor. It captures the nodes it spans when it is created; editing the document afterwards can leave it describing a span that no longer exists, and the operations then throw rather than silently doing something else.

Moving honors the model's one-parent invariant: a move detaches every node and re-adds it, and never produces a node reachable from two parents. Copying deep-clones, so the copy shares no mutable state with the original.

DropCap

A paragraph's drop cap as the document holds it (Phase 171).

DropCapEditingExtensions

Phase 171 (WQ-0151): a drop cap given to a paragraph, changed and taken away as an edit, as Word's Insert > Drop Cap does. The dropped text (any leading punctuation and the first letter) becomes a paragraph of its own before the rest, framed as a drop cap, its line exact, the cap sized and lowered to Word's numbers (DropCapGeometry); removing it puts the text back at the paragraph's start without its size and lowering. One undo step each.

DropCapSettings

A drop cap's settings, as Word's Drop Cap dialog sets them (Phase 171).

EnvelopeDocument

An envelope as Word builds it (Phase 170): Mailings > Envelopes (the addresses on it) and Start Mail Merge > Envelopes (the delivery address left empty for the fields), from an EnvelopeLayout.

EnvelopeEditingExtensions

Mailings > Envelopes > Add to Document and Change Document (Phase 173, WQ-0154): the envelope Word builds (EnvelopeDocument) as the document's first section, before the letter, as one undoable edit.

EnvelopeLayout

An envelope's size and where its addresses go, as Word's Envelope Options take them (Phase 170). Integer twips; a null position is Word's automatic one (the delivery address centred at the bottom, the return address at the margin's top left).

EquationEdit

The record of an equation edit (Phase 166): the document edit, undone and redone as any other, and where the caret goes.

EquationEditingExtensions

Equations edited at a position inside them (Phase 166): text typed into and deleted from a slot, a structure put in (the selection, if any, becoming its base), a whole equation inserted. Each is one DocumentEdit; an equation an edit changes is written from its model from then on (IsEdited), and undoing the edit puts back the exact model and flag it had.

ExtendedPropertiesEditingExtensions

The document properties of docProps/app.xml (Word's File > Info: Manager and Company), read and set as an edit (WQ-0131). The part rides through a load as a preserved part; these read it and rewrite it in place, so every element this model does not name (the template, the statistics, the application, the heading pairs, anything else) is kept as it was.

FindOptions

How a search treats case, word boundaries and pathological patterns.

FindReplaceExtensions

Plain and regular-expression find and replace over document text, preserving formatting.

What a match may cross. A match lives inside one paragraph and may span any number of runs, whatever their formatting — that is the whole point, since Word splits a sentence into runs for reasons that have nothing to do with its words. It may also cross bookmark markers, which are zero-width annotations. It may not cross a field character, field instruction text, a hyperlink boundary, a break, an image, a shape, a note reference, a content control or preserved unknown markup. Those carry a target, an instruction or content of their own, and text spliced across one of them would either change what the field or link means or be silently discarded the next time the field is updated.

Revisions. Searching sees the same text GetText(DomNode, RevisionView) reports for Final: deleted runs are not searchable, inserted runs are. A replacement inherits the revision mark of the run the match started in, so replacing inside tracked-inserted text stays tracked-inserted.

Ordering. Matches are returned in document order and never overlap: scanning resumes at the end of each match. Zero-length regular-expression matches are skipped — they identify no content to replace and would not terminate.

FormattingEditingExtensions

Formatting, styles and lists applied to a DocumentSpan as DocumentEdits: each can be undone exactly and names the paragraphs it changed, as the text edits of TextEditingExtensions do.

FragmentEditingExtensions

Formatted content copied out of a span and inserted at a position, as Word's copy and paste (keep source formatting) do (WQ-0095): each insertion one DocumentEdit that undo takes back exactly, definitions it added included.

HeaderFooterEditingExtensions

A section's headers and footers added, removed and linked as DocumentEdits, and a field inserted at a position, as Word does (WQ-0096). Text in a header or footer is edited through the same position edits as the body's: its paragraphs are the document's.

HyperlinkEditingExtensions

Hyperlinks added, inserted, changed and removed as DocumentEdits, as Word's Insert Link, Edit Link and Remove Link do (WQ-0094): each can be undone exactly and names the paragraphs it changed.

HyperlinkTarget

Where a hyperlink goes: an address (a URI, a mailto: address, a file path) or a bookmark in the same document, with an optional tooltip. Made by ToUri(string, string?) or ToBookmark(string, string?), which check the values; used by the edits of HyperlinkEditingExtensions.

ImageEditingExtensions

A picture already in the document resized, moved or copied, as DocumentEdits: each can be undone exactly and names the paragraphs it changed, as the edits of StructureEditingExtensions do.

IndexEditingExtensions

Word's References > Mark Entry and Insert Index as undoable edits (tools/Probe-WordIndex.ps1, WQ-0113): an XE field after the marked text, an INDEX field in a continuous section of its own with its columns, its entries in the Index 1-9 styles, rebuilt by an update with the page numbers PageNumberAt gives.

IndexEntryOptions

An index entry Mark Entry writes (an XE field).

IndexOptions

How Insert Index lays out an index (an INDEX field).

LabelLayout

A label's geometry, as Word's Label Options take it (Phase 168): the page, where the first label starts, a label's size, the distance from one label to the next across and down, and how many there are. Integer twips.

LabelSheet

A sheet of labels as Word builds it (Phase 168): Mailings > Labels > New Document (one address in every label) and Start Mail Merge > Labels (a merge sheet), from a LabelLayout; and Update Labels.

ListLibrary

Word's list galleries (Home > Bullets, Numbering, Multilevel List) as Word for Microsoft 365 applies them, read level by level with tools/Probe-WordListLibrary.ps1 (WQ-0100). A single-level entry's deeper levels are Word's default ones for its kind.

ListTemplate

A list's definition as Word's galleries offer it: up to nine levels, applied with ApplyListTemplate(WordDocument, DocumentSpan, ListTemplate).

MergeFieldEditingExtensions

Phase 161 (WQ-0134): a merge field inserted as Word's Mailings > Insert Merge Field writes one, before any data: MERGEFIELD Name with «Name» as its result, which proofing skips.

MergeOptions

How one document is merged into another.

MergeRuleEditingExtensions

Phase 167: Word's Mailings > Rules, each a field as Word's dialog writes it (tools/Probe-WordMergeRules.ps1): IF, NEXTIF and SKIPIF around a nested MERGEFIELD of the compared field, NEXT, MERGEREC and MERGESEQ; each with the text Word shows before any data. One undo step each.

NoteConversionExtensions

Word's References > Footnotes > Convert as undoable edits (WQ-0116, tools/Probe-WordNoteConvert.ps1): footnotes to endnotes, endnotes to footnotes, the two swapped, or one note; and a note inserted with a custom mark.

NoteEditingExtensions

Inserts footnotes and endnotes as undoable edits, as Word's References > Insert Footnote and Insert Endnote do (WQ-0104). Deleting a note's reference removes the note (DeleteRange(WordDocument, DocumentSpan)).

PlaceholderExtensions

Fills {{name}} placeholders in document text from a set of values.

A placeholder is ordinary text, so this inherits everything FindReplaceExtensions guarantees: a placeholder may be split across any number of runs — which Word does routinely, for reasons that have nothing to do with its words — the substituted value inherits the placeholder's formatting and revision mark, and the surrounding runs are coalesced afterwards. It may not cross a field, hyperlink, content control or image boundary.

Scope is the root you call it on. These hang off DomNode, not WordDocument. Called on a document they reach the body, headers, footers, footnotes, endnotes and text inside shapes — so a letterhead header is filled too. Called on a Table, a TableRow or a TableCell they touch nothing outside it, which is how one table among many is filled.

One pass. Every placeholder is substituted in a single scan, so a value that itself contains something shaped like a placeholder is never substituted into. Filling key by key instead would make the output depend on the order the keys happened to be enumerated in.

A placeholder names at least one character, so an empty {{}} names nothing and is left alone by every action including Clear.

This is deliberately a flat substitution: no conditionals, no repetition, no nested records. A template that needs a region repeated per record wants DocWright.MailMerge, where that grammar already lives.

PlaceholderOptions

How placeholders are recognized and how their values are formatted.

PlaceholderResult

What a placeholder substitution did.

ReplaceOptions

How a replacement is formatted and how the document is tidied afterwards.

SectionEditingExtensions

Section breaks inserted and removed as undoable edits, as Word does them (WQ-0098, tools/Probe-WordSectionBreaks.ps1).

ShapeEditingExtensions

Shapes edited as Word edits them (Phase 164): inserted from a preset, moved and wrapped, resized, turned and mirrored, refilled, re-outlined and changed to another preset. Each is one DocumentEdit, undone to exactly what was there.

StructureEditingExtensions

Tables and inline pictures inserted and edited at a position, as DocumentEdits: each can be undone exactly and names the paragraphs it changed, as the text edits of TextEditingExtensions do.

StyleDefinitionEditingExtensions

Changes style definitions as undoable edits, as Word's Styles pane does (WQ-0103): Modify a style, Update a style to Match Selection, and Create a Style from the selection's formatting. A changed definition reaches every paragraph and run that uses it through the style chain; each edit reports every paragraph of the document changed.

StyleEditingExtensions

Applies styles and direct formatting to paragraphs, runs and ranges.

Formatting is layered with the model's own OverlayOnto, which copies only the values a bag actually specifies. Applying new CharacterFormat { Bold = true } therefore sets bold and touches nothing else — it does not stamp the rest of the bag with defaults, and everything left null keeps inheriting from the style chain.

A style id is validated against the document's style table before it is written. A dangling reference is not a harmless no-op: the resolver reports DXP1002 and silently resolves without it, so the caller would see formatting that never arrives.

StyleUsage

Which styles a document's text uses, as a styles pane's "in use" view shows them: the body, headers, footers, footnotes and endnotes (shape text included) are counted.

TableFormattingEditingExtensions

A table's, its rows' and its cells' formatting changed as undoable edits (Word's Table Design and Layout tabs), as Word writes them (WQ-0099, tools/Probe-WordTableDesign.ps1).

TableGeometryExtensions

Word's table geometry as undoable edits (WQ-0117, tools/Probe-WordTableAutoFit.ps1): Layout > AutoFit, Distribute Columns, and a column's width (Table Properties > Column).

TableOfContentsEditingExtensions

A table of contents inserted and rebuilt, and fields updated, as undoable edits (Word's References > Table of Contents, Update Table and F9), as Word writes them (WQ-0097, tools/Probe-WordTableOfContents.ps1).

TableOfContentsOptions

What a table of contents lists and how (Word's References > Table of Contents dialog).

TableOfContentsStyle

A style a table of contents lists besides the headings (Word's Table of Contents Options, \t).

TextEditingExtensions

Changes document text at DocumentPositions the way Word does when a person types, deletes, presses Enter or Backspace: insert text, delete a span, split a paragraph, merge a paragraph with the one before it, replace a span. Each returns a DocumentEdit that undoes the edit exactly.

TextMatch

One match of a search.

ThemeEditingExtensions

Phase 159 (WQ-0132): a document's theme colours and theme fonts set as an edit, as Word's Design > Colors and Fonts and their Customize dialogs set them. The theme part (RawXml) is rewritten where it changed only, so everything the model does not name is kept; a document with no theme part gets one; and every colour that names a theme slot has its cached RGB refreshed, as Word rewrites it.

TypingCorrection

One correction a keystroke made: what kind, where its result is, and the text it replaced.

TypingCorrectionOptions

Which of Word's AutoFormat As You Type and AutoCorrect corrections TypingCorrections makes. Every one is on by default, as in a new installation of Word (WQ-0108).

TypingCorrections

Word's AutoFormat As You Type and AutoCorrect, as edits a consumer applies after a keystroke (WQ-0108): smart quotes, dashes and symbols, ordinals, fractions, hyperlinks, automatic lists, borders, and capitals. Each call looks at what was just typed and returns the correction Word would make at that keystroke, or an empty edit; applied as an edit of its own, so one undo takes back the correction and leaves what was typed, as Word's does.

WatermarkEditingExtensions

Phase 160 (WQ-0133): a text watermark read, set and removed as an edit, as Word's Design > Watermark does. Word keeps one per document: setting one takes every other away and puts the new one in the header in effect for a section's pages of a kind; removing takes every one away. The shape is written as Word writes it, its typed model as the reader builds it, so it lays out behind the text at once and saves without a reload.

WordWildcards

Word's Find with "Use wildcards" (WQ-0121): its pattern language turned into a .NET regular expression, and its replacement language (\1, ^&) expanded for a match. A wildcard search always matches case, as Word's does.

Structs

DocumentPosition

A point in a paragraph's content, where text is inserted, a span starts or ends, or a paragraph is split.

DocumentSpan

The content between two positions. The positions may be given in either order; the span keeps them in document order.

DropCapGeometry

What a drop cap's paragraph is given, in Word's numbers (Phase 171, WQ-0151): the cap's size and lowering, and its paragraph's exact line height. DocWright.Layout.DropCapMeasurer measures it from the faces the engine draws with, as Word measures it from the letter's glyph and the text's line pitch.

PlacedShape

A shape and where its box is, before any turn (Phase 179): what grouping needs from the caller's layout.

Enums

BookmarkInsertPosition

Where content is inserted relative to a bookmark.

CaptionNumberFormat

How a caption's number is written (Insert Caption, Numbering): the SEQ field's * format.

CaptionPosition

Where a caption goes: above or below what it captions (Insert Caption, "Position").

CellBorderSides

Which edges of a block of cells Word's Borders gallery sets.

CellShift

Which way Delete Cells closes the gap (Word's Delete Cells dialog; whole rows and columns are DeleteRows(WordDocument, TableCell, TableCell) and DeleteColumns(WordDocument, TableCell, TableCell)).

CoverPageField

A field a cover page shows: a document property, through a plain-text content control bound to it.

CrossReferenceKind

What a cross-reference shows (Word's Insert > Cross-reference, "Insert reference to").

HeaderFooterType

Which pages of a section a header or footer is for (ECMA-376 §17.18.36 ST_HdrFtr).

IndexHeadings

What goes before each letter's entries in an index (INDEX \h).

ListKind

The kind of list ApplyList(WordDocument, DocumentSpan, ListKind) puts paragraphs in.

MergeComparison

How a mail merge rule compares a field with a value (Word's Rules dialogs).

ShapeDash

The dashes of Word's Shape Outline > Dashes (Phase 178).

ShapeLineKind

The lines and connectors of Word's Insert > Shapes > Lines (Phase 178).

StyleConflictResolution

What happens when a style id exists in both documents being merged.

TableAutoFit

How Layout > AutoFit sizes a table (Word's three choices).

TypingCorrectionKind

What a typing correction did (Word's AutoCorrect Options button names it).

UnresolvedPlaceholderAction

What to do with a placeholder the data supplies no value for.