Table of Contents

Lay out again after an edit

An editor, a live preview or a server that re-renders after every change needs the layout again each time the document changes. A LayoutSession keeps what it computed, so laying out again after an edit costs the edit, not the document, and tells you which pages are new.

Relayout after an edit

using DocWright.Core.Rendering;
using DocWright.Dom;
using DocWright.Dom.Editing;
using DocWright.Fonts;
using DocWright.Layout;

using var document = new WordDocument();
for (int i = 1; i <= 120; i++)
{
    document.AppendParagraph($"Paragraph {i}: the quick brown fox jumps over the lazy dog, then runs on into the next line of text.");
}

var session = new LayoutSession(new FontEngine());
LayoutDocument first = session.Layout(document);
Console.WriteLine($"Laid out {first.PageCount} pages");

// Type one character in the middle of the document.
Paragraph paragraph = document.Sections[0].Blocks.OfType<Paragraph>().ElementAt(60);
DocumentEdit edit = document.InsertText(DocumentPosition.InParagraph(paragraph, 10), "x");
LayoutUpdate update = session.Relayout(document, edit.ChangedParagraphKeys);

Console.WriteLine($"Pages {update.FirstChangedPage}..{update.LastChangedPage} changed");
Console.WriteLine($"{update.ParagraphsMeasured} paragraph measured, {update.ParagraphsReused} reused");
for (int page = 1; page <= update.Document.PageCount; page++)
{
    string state = update.IsPageChanged(page) ? "new" : "the previous instance";
    Console.WriteLine($"  page {page}: {state}");
}

Output

Laid out 3 pages
Pages 2..2 changed
1 paragraph measured, 119 reused
  page 1: the previous instance
  page 2: new
  page 3: the previous instance
Member Is
session.Layout(document) The first, full layout. The session keeps it.
session.Relayout(document, keys) The layout after a change. keys is DocumentEdit.ChangedParagraphKeys, or null.
update.Document The new layout, equal to a full layout of the document as it now is.
update.FirstChangedPage, update.LastChangedPage The 1-based range of pages that differ from the page at the same position before; 0 when nothing changed.
update.IsPageChanged(n) Whether one page is new. A page that is not is the previous LayoutPage instance itself.
update.PreviousPageCount The page count before.
update.ParagraphsMeasured, update.ParagraphsReused How much work the call did.

The result is a full layout's

The session resolves the document again on each call and reuses the measurement of every paragraph whose resolved content and measuring conditions it has seen before, and the primitives of every line that lands where it did. It decides by comparing, never by trusting what you tell it: the keys you pass are a hint, and a wrong or missing one cannot leave a page stale. A style, numbering or settings change reaches every paragraph it touches the same way.

For tests, new LayoutSessionOptions { VerifyAgainstFullLayout = true } also lays the document out from scratch on every Relayout and throws if the two differ.

What it costs

Measured on a 30-page document of mixed paragraphs and tables, after warm-up:

Edit p95 at 10 % / 50 % / 90 % of the document
Insert one character 4.1 / 3.7 / 3.9 ms
Split a paragraph 3.7 / 13.9 / 4.2 ms
Merge two paragraphs 12.2 / 4.3 / 8.4 ms
Delete across three paragraphs 62.1 / 52.6 / 12.9 ms

A full layout of the same document takes about 100 to 170 ms. A delete that pulls text up reflows every later page, and each of those is drawn again.

Rules

  • A session is single-threaded: one caller at a time, with the document not changing during a call. Different sessions are independent.
  • It holds at most the last layout's measurements.
  • A paragraph that holds an image, a shape, a field or a note reference is measured on every call.
  • A page that draws a metafile picture or a picture fill is reported changed whenever it is laid out again. That costs a redraw, never a stale page.
  • Diagnostics come from what was measured again; a reused paragraph reports nothing a second time.