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:Sourcescustom 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_Refbookmark 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 Namewith«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,NEXTIFandSKIPIFaround a nestedMERGEFIELDof the compared field,NEXT,MERGERECandMERGESEQ; 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. Applyingnew 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
DXP1002and 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.DropCapMeasurermeasures 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.