Table of Contents

Lay a document out for the screen

A page layout is what prints. A reader on a screen, an editor's Web Layout, Draft and Outline views, or a long image of a document's text want the text as one continuous flow instead. Give StyleResolver a ScreenView and layout produces that flow.

Web layout and Draft

using DocWright.Core.Primitives;
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 <= 40; i++)
{
    document.AppendParagraph($"Paragraph {i}: the quick brown fox jumps over the lazy dog, then runs on into the next line of text.");
}

// Two columns on the page: a screen view lays the same text out in one.
Paragraph first = document.Sections[0].Blocks.OfType<Paragraph>().First();
var here = new DocumentSpan(DocumentPosition.StartOf(first), DocumentPosition.StartOf(first));
document.FormatSections(here, section => section.Columns = new ColumnsFormat { Count = 2 });

var fonts = new FontEngine();
LayoutDocument Lay(ScreenView? view)
{
    ResolvedDocument resolved = StyleResolver.Resolve(document, new ResolveOptions { Fonts = fonts, View = view });
    return new LayoutEngine(fonts).Layout(resolved);
}

LayoutDocument pages = Lay(null);
Console.WriteLine($"Pages: {pages.PageCount}, each {pages.Pages[0].Width.Value} x {pages.Pages[0].Height.Value} twips");

// Web layout: the text wrapped to a window 5 inches wide, in bands of about 6 inches.
LayoutDocument web = Lay(new ScreenView(ScreenViewKind.Web) { Width = new Twips(7200), BandHeight = new Twips(8640) });
int y = 0;
foreach (LayoutPage band in web.Pages)
{
    Console.WriteLine($"Web band {band.PageNumber}: draw at y = {y}, {band.Width.Value} x {band.Height.Value} twips");
    y += band.Height.Value;
}

// Draft: one column as wide as the page's first column, so the lines break where the page's do.
LayoutDocument draft = Lay(new ScreenView(ScreenViewKind.Draft));
Console.WriteLine($"Draft: {draft.PageCount} band(s), {draft.Pages[0].Width.Value} twips wide");

Output

Pages: 1, each 12240 x 15840 twips
Web band 1: draw at y = 0, 7200 x 8509 twips
Web band 2: draw at y = 8509, 7200 x 8510 twips
Web band 3: draw at y = 17019, 7200 x 1379 twips
Draft: 2 band(s), 4320 twips wide
Outline, everything:
  OutlineHeading          marker at x =    0: Chapter one
  OutlineBody             marker at x =  720: Its introduction, as body text.
  OutlineHeading          marker at x =  720: A section
  OutlineBody             marker at x = 1440: The section's text.
  OutlineHeadingEmpty     marker at x =    0: Chapter two
Outline, Show Level 1:
  OutlineHeading          marker at x =    0: Chapter one
  OutlineHeadingEmpty     marker at x =    0: Chapter two
Outline, Chapter one collapsed:
  OutlineHeadingCollapsed marker at x =    0: Chapter one
  OutlineHeadingEmpty     marker at x =    0: Chapter two

Bands

The flow comes out in bands: pages without margins, headers, footers, columns, page borders or line numbers, each as tall as what it holds. Draw them one under the other, with no gap, and you have the whole text, line for line, as one band of unbounded height would hold it. They exist so that code which draws, compares or sends pages has pages of bounded size.

BandHeight (11 inches unless you set it) only decides how much a band holds: it takes whole lines and whole table rows until it holds about that much. Nothing in the flow depends on where a band ends. Keep with next, keep lines together, widow control and page break before do nothing between two bands, a table's header rows are not repeated, and a manual page or column break only ends its line.

The two views

ScreenViewKind.Web ScreenViewKind.Draft
Width of a section's band ScreenView.Width The section's first text column on its page, so lines break where the page's do
Floating pictures, shapes, text boxes Laid out, in the band of their anchor Not laid out
Page colour Painted over each band Not painted

In both, every section is one column and starts a band, and footnotes are not laid out (their reference marks are); endnotes flow where they do on pages.

Outline

ScreenViewKind.Outline lays the same flow out as Word's Outline view shows a document: every paragraph at its outline level's indent, behind a marker that says what it is, and with none of its own paragraph formatting.

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

using var report = new WordDocument();
Paragraph chapter = report.AppendParagraph("Chapter one");
report.AppendParagraph("Its introduction, as body text.");
Paragraph section = report.AppendParagraph("A section");
report.AppendParagraph("The section's text.");
Paragraph second = report.AppendParagraph("Chapter two");
foreach ((Paragraph heading, string style) in new[] { (chapter, "heading 1"), (section, "heading 2"), (second, "heading 1") })
{
    report.ApplyBuiltInStyle(new DocumentSpan(DocumentPosition.StartOf(heading), DocumentPosition.StartOf(heading)), style);
}

// Source references give each marker its paragraph's key, and are what collapsed headings are named by.
LayoutDocument Outline(ScreenView view)
{
    var options = new ResolveOptions { Fonts = fonts, EmitSourceReferences = true, View = view };
    return new LayoutEngine(fonts) { EmitSourceReferences = true }.Layout(StyleResolver.Resolve(report, options));
}

void Print(string title, LayoutDocument outline)
{
    Console.WriteLine(title);
    foreach (LayoutPage band in outline.Pages)
    {
        Dictionary<int, string> lines = band.Primitives.OfType<GlyphRun>()
            .GroupBy(run => run.BaselineY.Value)
            .ToDictionary(line => line.Key, line => string.Concat(line.OrderBy(run => run.BaselineX.Value).Select(run => run.Text)));
        foreach (LayoutMark marker in band.Primitives.OfType<LayoutMark>().OrderBy(mark => mark.Baseline.Value))
        {
            Console.WriteLine($"  {marker.Kind,-23} marker at x = {marker.X.Value,4}: {lines[marker.Baseline.Value]}");
        }
    }
}

var everything = new ScreenView(ScreenViewKind.Outline) { Width = new Twips(9000) };
var chapters = new ScreenView(ScreenViewKind.Outline) { Width = new Twips(9000), ShowLevel = 1 };
var collapsed = new ScreenView(ScreenViewKind.Outline) { Width = new Twips(9000), CollapsedHeadings = new[] { chapter.NodeId.Value } };
Print("Outline, everything:", Outline(everything));
Print("Outline, Show Level 1:", Outline(chapters));
Print("Outline, Chapter one collapsed:", Outline(collapsed));

The output above shows it: three views of one document, each line with its marker.

  • A paragraph whose outline level is 1 to 9 (from its style or its own) is a heading of that level. Its marker stands at (level - 1) * ScreenView.OutlineIndentTwips, half an inch a level as Word sets it, and its text ScreenView.OutlineMarkerWidthTwips further in. Body text and tables stand a level under the heading before them.
  • The markers are LayoutMarks: OutlineHeading for a heading with something under it (Word draws a plus), OutlineHeadingEmpty for one with nothing (a minus), OutlineHeadingCollapsed, and OutlineBody (a small circle). They are emitted whether formatting marks are on or not, and the built-in renderers do not draw them: the code that draws the screen does. ParagraphKey says which paragraph a marker belongs to, so a click on it can collapse that heading.
  • ShowLevel 1 to 9 lays out the headings down to that level and nothing else; ScreenView.AllLevels (the default) lays out everything.
  • CollapsedHeadings holds paragraph node keys. A collapsed heading is laid out; what is under it, down to the next heading of its level or above, is not.
  • Indents, space before and after, line spacing, alignment, borders and shading are not shown, as in Word. The text's own formatting is.
  • Floating objects, footnotes and the page colour are not laid out. Word's "Show first line only" and "Show text formatting" switches are not built.

In a layout session

LayoutSessionOptions.View may change between two layouts of a session, so an editor switches views without opening the document again. Set it to null for the pages. An edit made while a view is on lays out again at the cost of the edit, and positions (glyph run sources, LayoutLines, cell and column regions) name the same document text as they do on a page.

Rules

  • Width is 1440 to 200000 twips and BandHeight 1440 to 10000000; a value outside is refused with ArgumentOutOfRangeException when the document is resolved.
  • ResolvedDocument.View says which view a document was resolved for, or null.
  • Both renderers take the bands as pages of their own sizes.
  • Three things are not exactly the unbroken flow: a table row taller than BandHeight is split where its band ends; a line set further below the one before it than a band is tall is set a band's height below; and an underline or a strikethrough can stand a 600th of an inch higher or lower in a band, because Word places it on its device grid from the line's place on the page.
  • Word's Web Layout shows footnotes after the text, wraps a Draft to the window on request and fits an AutoFit-to-window table to the view. DocWright does none of the three yet.