Layout engine
DocLayout turns a DocumentModel into pages and draws them. This document covers typesetting, caching, tables, drawing and the geometry queries the editor uses. The flow of blocks into columns and pages has its own document: pagination.md. PDF output is in pdf.md.
| Part | Code (Packages/ORIXDocsKit/Sources/) |
|---|---|
| Font resolution | DocLayout/Fonts.swift |
| Paragraph typesetting | DocLayout/ParagraphLayout.swift |
| Layout result, cache, table layout types | DocLayout/DocumentLayout.swift |
| Flow into pages | DocLayout/Paginator.swift |
| Drawing | DocLayout/PageRenderer.swift |
| Caret, selection, hit testing | DocLayout/Geometry.swift |
| Equations | DocMath/MathRenderer.swift |
| Tests | Tests/DocLayoutTests/PaginationTests.swift (TypesettingTests, GeometryQueryTests, TableLayoutTests), PDFTests.swift, SmokeTests.swift |
Why Core Text and an own paginator
The decision and its evidence are in technology-evaluation.md, section 1. In short: NSTextLayoutManager (TextKit 2) has a single text container and viewport-based layout, so it cannot flow text through a sequence of pages with exact geometry for the whole document; TextKit 1 paginates through multiple containers but offers no footnote placement, repeated table header rows, keep rules or widow/orphan control. CTTypesetter returns one line at a time for a width the caller chooses, which is what a paginator needs, and the same drawing code can target the screen, a bitmap or a PDF context. The cost is that everything NSTextView gives for free must be written by hand (text-engine.md).
flowchart LR
M[DocumentModel] --> N[Numbering]
M --> PG[Paginator]
N --> PG
PG -->|"paragraph + environment"| LC[LayoutCache]
LC -->|miss| PL[ParagraphLayout]
PL --> FC[FontCache]
PL --> MR[MathRenderer]
LC --> PG
PG --> DL["DocumentLayout: pages of fragments"]
DL --> PR[PageRenderer]
DL --> GQ["Geometry queries"]
PR --> SC["Screen: EditorCanvasView"]
PR --> BM["Bitmap: thumbnails, previews"]
PR --> PDF["PDF context: PDFPublisher"]
GQ --> SC
Font resolution
FontCache.shared.font(family:size:weight:italic:smallCaps:) returns a CTFont and memoises it by those five values (lock-protected).
- System designs by name.
New York,SF Pro(alsoSF Pro Display,SF Pro Text,System),SF Pro RoundedandSF Monoare not font files; they map toNSFontDescriptor.SystemDesign.serif,.default,.rounded,.monospacedonNSFont.systemFont(ofSize:weight:). - Weights. The model's CSS-like weight (100–900;
boldis 700) maps to anNSFont.Weightfor system designs (nsWeight) and to akCTFontWeightTraitvalue for other families (ctWeight); the bold symbolic trait is requested from 600 up. - Italic. Requested as a symbolic trait. A family that yields a font without the italic trait gets a synthetic slant (a copy with the matrix
c = 0.2). System designs take the italic trait on the descriptor and get no synthetic fallback. - Small capitals. When
smallCapsis set the font descriptor gets OpenType feature type 37, selector 1 (lowercase small capitals). Nothing is synthesised for fonts that lack the feature. - Superscript and subscript use the same family at 0.66 of the size (
font(for:scale:)), with a baseline shift of +0.33 or −0.14 of the font size added inParagraphLayout. - Missing families. The list of installed families is read once (
CTFontManagerCopyAvailableFontFamilyNames, lower-cased). A family that is neither installed nor a system design is recorded inmissingFamiliesand replaced by Times New Roman.DocumentConverter.preflight(_:format:)reports the list as a "Missing fonts" warning before a PDF export. The set only grows during the life of the process. - No-break space correction.
noBreakSpaceCorrection(_:)measures the difference between the advances of U+0020 and U+00A0 in a font. Some fonts (the code comment names Charter) give the no-break space a figure-wide advance, which shows as a visibly wide gap, for example in "Figure 3" or before French punctuation.ParagraphLayoutadds the difference as kerning (or to the tracking value when the run already uses tracking, because the two do not add up on one character) on every U+00A0 of a run.
Per-glyph fallback for characters a font does not contain (CJK, emoji, symbols) is left to Core Text; the code sets no cascade list.
Building the attributed string
ParagraphLayout.init(_:env:) receives a paragraph and a ParagraphEnvironment (style sheet, layout options, width, list label and level, heading number, texts of text-like inline objects, exclusions, math typeface, colour override, language).
Invariant: one model character is one display character. The attributed string has exactly the UTF-16 length of the paragraph (precondition(text.length == length)), so a model offset is a Core Text string index and no mapping table exists. To keep it:
- an inline object stays the single character U+FFFC and gets a
CTRunDelegatethat supplies its width, ascent and descent; allCapstext is replaced by its uppercase form only when the UTF-16 length is unchanged (so "ß" is left alone rather than becoming "SS");- tracked deletions hidden by
LayoutOptions.markup == .nonekeep their characters but each gets a zero-size delegate, so they take no room (TypesettingTests.trackedDeletionsAreHiddenWithoutMarkup); - the only exception is a hyphenated line (below).
Each run carries a RunInfo object under the private attribute key orix.run (resolved formatting, colour, revision, comment flag, box, underline and strikethrough). Underline and strikethrough are not Core Text attributes; the renderer draws them. With markup shown, an inserted run is coloured per author (ReviewColors.color(for:), a hash into six colours) and underlined, a deleted run is coloured and struck through.
Inline boxes
InlineBox holds the metrics and what to draw:
| Content | Source | Notes |
|---|---|---|
.image, .shape |
Inline images and shapes | Width and height from the object (bounding box of a rotated image); ascent = height, descent 0. |
.equation(MathLayout) |
.equation |
Typeset by MathRenderer.layout at 1.1 × the run's font size. |
.text(CTLine, rise:) |
Note marks, citations, cross-references, fields | The displayed string comes from env.boxTexts in order of appearance; it is typeset as its own CTLine and behaves as one unbreakable box. Note marks are superscript. |
.dropCap |
Drop capital | See below. |
.anchor |
Bookmarks, anchors of floating objects, hidden deleted text | Zero size. |
Floating images and shapes are not in the line: the paragraph records a FloatBox (rectangle relative to the paragraph's top-left corner, from alignment and offsets) and leaves a zero-size anchor at the object's position.
Line breaking
For each line the builder asks extent(at:height:first:) for the usable horizontal extent at the current y, then CTTypesetterSuggestLineBreakWithOffset for a break in that width, then CTTypesetterCreateLineWithOffset.
- Indents. Left and right indents, and a first-line indent that may be negative (hanging). A list label or heading number changes the first-line start (below).
- Exclusions. An
Exclusionnarrows lines between two y values from the left and/or right. They come from floats of earlier paragraphs (passed in by the paginator), from the paragraph's own floats (.squarenarrows on the side the float is on when its centre is in the outer 40 % of the column, otherwise the lines skip below it;.topAndBottomalways skips;.behindTextand.inFrontOfTextexclude nothing), and from a drop cap. When fewer than 40 pt would remain, the line skips to the bottom of the exclusion. Test:floatingObjectsNarrowTheLinesBesideThem. - Drop caps. With
dropCapLines ≥ 2(capped at 6), on a paragraph that is not a list item and starts with a letter in an untracked text run, the first composed character gets a delegate box as wide as the enlarged glyph and an exclusion pushes the following lines aside. Test:dropCapNarrowsTheFollowingLines. - Justification.
CTLineCreateJustifiedLinewith factor 1.0, for every line except the last and those ending in a forced break. Test:justifiedLinesFillTheMeasureExceptTheLast. - Right-to-left.
rightToLeftsets the base writing direction; a left-aligned right-to-left paragraph is aligned right. Test:rightToLeftParagraphsAlignRight. - Empty paragraphs and a paragraph ending in U+2028 get a zero-width line so the caret has a place.
Hyphenation
Enabled per paragraph (hyphenate, off by default) when CFStringIsHyphenationAvailableForLocale holds for the language of the last run, else of the document. After Core Text suggests a break, the builder looks at the word that would start the next line: if the line ends with a space, contains no tab, and the word has at least five letters, it asks CFStringGetHyphenationLocationBeforeIndex for break points from the end of the word backwards and takes the first one for which the line plus a hyphen fits.
A hyphenated line is typeset separately: a new CTLine is created from the substring plus "-". Its string indexes start at 0, so LayoutLine.indexBase holds the offset to add to obtain model offsets (xPosition(for:) and offset(atX:) apply it). Test: hyphenationBreaksLongWordsOnlyWhenEnabled (lines still cover every character exactly once).
Tabs and leaders
Tab stops (left, centre, right) become CTTextTabs measured from the column's left edge, with a default interval of 36 pt; a decimal tab is a right tab whose column terminators are "." and ",". Header and footer paragraphs without explicit tabs get a centre tab at half the width and a right tab at the full width. Leaders are not part of the line: PageRenderer.drawLeaders fills the gap of each tab character with dots, dashes or a rule.
Line height
For each line, natural = ascent + descent + leading from CTLineGetTypographicBounds (the paragraph font's metrics when the line is empty), and fontLine is the same sum for the font of the last run:
LineSpacing |
Line height |
|---|---|
.multiple(k) |
natural + (k − 1) × min(natural, fontLine) — a tall inline object does not multiply the extra spacing |
.exact(v) |
v |
.atLeast(v) |
max(v, natural) |
The baseline is placed so that ascent + descent is centred in the line box. Test: lineSpacingModes.
List labels and heading numbers
Labels are never in the text; Numbering computes them. A list label is a separate CTLine (LabelBox) drawn hanging at indent − hanging of the ListLevel, and the text starts at the level's indent (or after the label if it is wider). A heading number is drawn at the first-line start and the text follows after a gap of 0.55 × the font size. Labels use the size and colour of the first run and the paragraph style's weight. Test: listLabelsHangInTheIndent.
The layout cache
LayoutCache (DocumentLayout.swift) avoids typesetting a paragraph again when nothing it depends on changed.
- Key. Entries are stored per paragraph id, up to three per id (a paragraph can legitimately have several layouts: different column widths, with and without neighbouring floats). An entry matches when the
Paragraphvalue is equal and width, list label, list level, heading number, box texts, exclusions, header/footer flag, colour override, layout options and math typeface are all equal. - Style sheet.
beginPass(styles:)empties the cache when theStyleSheetdiffers from the one of the previous pass: any style edit is a full relayout. - Generations. Each pagination pass increments a generation and stamps the entries it uses; every eighth generation
endPass()drops entries not used in the last eight, which removes layouts of deleted paragraphs. - Headers and footers. The same header paragraph appears on every page with different field values (page number, running head). With three slots per id it would be typeset again on almost every page of every pass, so these layouts live in a second dictionary keyed by paragraph id, box texts and width: one layout per distinct content.
hitsandmissesare public counters.removeAll()is called when a document is reloaded.
The cache has no lock: one cache serves one document on one thread at a time. Table layouts (TableLayout) are recomputed on every pass; only their cell paragraphs are cached.
Tables
Pass.tableLayout(_:width:) produces a TableLayout:
- Scaling. A table wider than its column (by more than 0.5 pt) has all its column widths scaled by the same factor and is reported in
DocumentLayout.overflowingTableIDs. Test:aTableWiderThanTheColumnIsScaledAndReported. - Cells. A cell covers
colSpangrid columns; its paragraphs are typeset at the cell width minus the style's padding, in the header text colour for header rows of a style that defines one. - Row heights. The tallest unmerged cell content plus padding, at least
minHeight, never under 14 pt. - Vertical merges. A
restartcell'srowSpancounts thecontinuecells below it in the same grid column; if its content is taller than the rows it covers, the last of those rows grows. Test:mergedCellsCoverTheirGrid. headerRowsis the number of leading rows withisHeader.
Splitting across pages is done by the paginator (pagination.md).
Equations
MathRenderer.layout(latex:fontSize:display:color:typeface:) typesets LaTeX with SwiftMath and caches the result (up to 4,000 entries, keyed by typeface, size, style, colour and source). The MathLayout wraps the NSImage returned by SwiftMath's MathImage.asImage(), which on macOS is created with a drawing handler, so drawing it replays glyph drawing into the destination context. The math typeface is chosen from the document's default font family (MathTypeface.matching(textFamily:)). A formula that does not parse is shown as its source in red monospaced text and carries an error (invalidEquationShowsItsSourceInsteadOfVanishing). Drawing is serialised by a lock.
The page renderer
PageRenderer.draw(page:in:) draws into a context whose origin is the page's top-left corner with y pointing down. The same code serves the canvas, thumbnails and previews (PDFPublisher.bitmap), printing and PDF.
Drawing order:
- page background (
PageSetup.background), else white paper whendrawsPaperis on (off for PDF); - watermark (not on blank parity pages), page border;
- floats with
.behindText; - tables: cell shading (cell, header or banded rows), then borders — cell overrides, else the table style's outer and inner lines; the
Academicstyle adds its three rules; - text fragments, in placement order (below);
- the other floats;
- footnote separator rules, column rules;
- break markers, unless
forPrint.
For a text fragment: paragraph shading and borders span the fragment; the list label or heading number is drawn with the first line; then each line is drawn run by run (drawLine): highlight or comment tint behind the run, the link hook, the inline box if any, the glyphs with CTRunDraw, then underline and strikethrough from the font's metrics (trailing white space excluded). Leaders are drawn last.
Screen-only decorations, all skipped when LayoutOptions.forPrint is set: the change bar in the margin beside lines that carry a tracked change, the comment tint, break markers (a dashed rule with a label supplied through MarkerLabels, or a rule alone for continuous section breaks). Focus mode dims every body paragraph but one (focusParagraphID).
RenderHooks lets a client observe drawing without the renderer knowing about PDF: link(rect, target) for every run with a link, and begin(role) / end() around text fragments (paragraph, heading level, list item, note), figures (images, shapes, equations, with alternative text) and tables. pdf.md describes how they are used.
Images are decoded once per asset (ImageStore, an NSCache limited to 512 MB of decoded pixels); a PDF asset is drawn as vector content (its first page); crop and rotation are applied at draw time; a missing or unreadable asset draws a labelled placeholder.
Geometry queries
Geometry.swift extends DocumentLayout; an index from (story, path) to fragments (fragments(story:path:)) backs all of them.
| Query | Result |
|---|---|
locate(story:position:upstream:preferredPage:) |
The page, fragment and line that display a position. upstream prefers the previous line at a line boundary; preferredPage selects the page for headers and footers, which repeat. |
caret(…) |
A 1.5 pt wide rectangle of the line's height. On an atomic block: the marker's or the generated block's leading edge. |
selectionRects(story:start:end:blocks:preferredPage:) |
One rectangle per line covered; a small extension where the selection continues past a paragraph end; whole rectangles for break markers and generated blocks. Test: selectionRectanglesCoverEveryLineOfTheRange. |
cellRect(block:row:cell:), columnBoundary(page:point:tolerance:), floatHit(page:point:) |
Table cell rectangle, column edge under the pointer, topmost floating object. |
hitTest(page:point:restrictTo:) |
Markers first; inside a table the cell under the point; otherwise the nearest fragment (vertical distance weighted four times the horizontal one), its line at the point's y, and LayoutLine.offset(atX:). Reports upstream affinity at the end of a wrapped line and onAtomicBlock for generated content. Tests: hitTestRoundTripsCaretPositions, hitTestingFindsTheCellUnderThePoint. |
lineRange(…) |
Model range of the visual line (Home/End), excluding a trailing forced break. Test: homeAndEndUseTheVisualLine. |
verticalMove(story:from:goalX:down:…) |
The position on the adjacent visual line nearest to goalX, across fragments and pages. In a table: first within the cell, then to the cell of the next or previous row nearest to goalX, then out of the table; entering a table picks the cell under the caret. Test: verticalMovementKeepsTheColumnAndCrossesPages. |
Limits
- Inline boxes are unbreakable. A citation, cross-reference, field value or note mark is one box; a long citation cannot wrap, and an inline image or equation wider than the line overflows it.
- First-fit line breaking. Breaks are those suggested by Core Text line by line; there is no paragraph-level optimisation. Hyphenation only considers the first word of the next line, only after a space, and uses one language per paragraph.
- Leaders: one leader style per paragraph — the first tab stop that has a leader decides for all tabs (
drawLeaders) — and none on hyphenated lines. - Small capitals and bold depend on what the font offers; only italic is synthesised.
- Bidirectional selections are approximated (text-engine.md).
- Rows do not split across pages, and nothing keeps the rows of a vertical merge together (pagination.md).
- Paragraph continuation beside a float: see pagination.md.
- Concurrency.
FontCacheandMathRendererare lock-protected andImageStoreis safe to share, butLayoutCacheis not thread-safe.Fonts.swiftreads the installed-family list once because, as its comment records, asking the font registry per family from many threads is slow and can stall. For the same reason the layout tests are run serially (swift test --no-parallel, see testing.md); batch processing bounds its concurrency (WorkflowRunner.runBatch(_:inputs:maxConcurrent:progress:)inDocAutomation, four files at a time by default). - Measured costs are in performance.md.