Constrained Streaming Layout

HotPDF can measure reusable elements without drawing, split paragraph, row, container, and custom elements into owned continuations, compose reusable page layers, stage completed pages in file-backed storage, apply paragraph page-break constraints, and expose bounded diagnostics

Reusable measure and draw contract

Derive from THPDFLayoutElement and implement side-effect-free Measure plus Draw; measurement receives only THPDFLayoutConstraints, so it has no page or document drawing surface

MeasureLayoutElement validates non-negative dimensions and computes Fits centrally from the same width and height constraints used for placement

THPDFLayoutElementKind lets ElementKind classify an implementation as lekParagraph, lekRow, lekContainer, or lekCustom, while ElementPath supplies stable diagnostic context

Split and overflow ownership

A splittable element returns THPDFLayoutSplit containing caller-owned placed and overflow elements; PlaceLayoutElement remeasures the placed head, draws it only when it fits, and transfers the tail into THPDFLayoutOverflow

THPDFLayoutOverflow records the source page and element path, owns the continuation by default, and transfers it explicitly through DetachElement

Declarative page layers

Register callbacks with AddPageLayer before BeginDoc by selecting plkBackground, plkHeader, plkFooter, or plkForeground

Each callback runs exactly once per page in background, header, document-content, footer, and foreground order and is isolated by a graphics-state save and restore pair

RemovePageLayer removes one registration by identifier, while ClearPageLayers resets the reusable composition before document generation starts

THPDFPageLayerRegistration stores the stable identifier, layer kind, and object-method handler used internally by the document's ordered registration list

Immediate page flushing

Set ImmediateFlushLayout before BeginDoc for reports whose page count is not known in advance

When a page closes, its final compressed or uncompressed content stream moves from memory to an owned temporary-file stream while the PDF object remains available for normal cross-reference and resource finalisation

ImmediateFlushedPageCount and ImmediateFlushedBytes report the amount of staged content, and temporary files are deleted when their owning streams are released

Paragraph pagination

ParagraphIndex := PDF.CreateParagraph(0, jtLeft, 36, 36, 36, 36);
PDF.ConfigureParagraphPagination(ParagraphIndex, True, 2, 2);
PDF.ConfigureParagraphDirection(ParagraphIndex, pdAuto);
PDF.BeginParagraph(ParagraphIndex);
PDF.CurrentParagraph.ShowUnicodeText(BodyText);
PDF.EndParagraph;

KeepWithNext moves a paragraph when it would consume the final line that should remain for following content
MinOrphanLines prevents too few opening lines from being left at the bottom of a page
MinWidowLines advances a break when too few closing lines would remain on the next page
Automatic continuation preserves the source page width, height, font, margins, and paragraph settings
When ParaAutoAddPage is false, overflow stops on the current page and produces an ldkOverflow diagnostic

Layout diagnostics

THPDFLayoutDiagnostic records the THPDFLayoutDiagnosticKind, source and related page indexes, affected rectangle, line count, and an English reason for each retained decision

THPDFLayoutDiagnosticArray is returned by GetLayoutDiagnostics, while GetLayoutDiagnostic supports indexed access without allocating a copy

LayoutDiagnosticLimit bounds retained records and LayoutDiagnosticDroppedCount reports decisions discarded after that limit

ldkAutomaticPageBreak reports an ordinary continuation
ldkKeepWithNext, ldkOrphanControl, and ldkWidowControl identify the constraint that moved a break
ldkOverflow identifies content stopped by disabled automatic pagination
ldkImmediateFlush identifies a closed page moved to file-backed storage
ldkPageLayer identifies a completed declarative page-layer pass

Paragraph direction

THPDFParagraphDirection provides pdAuto, pdLeftToRight, and pdRightToLeft

DetectParagraphDirection applies first-strong-character resolution across BMP and supplementary-plane RTL scripts, so neutral prefixes and secondary directional runs do not choose the wrong base direction

Use ConfigureParagraphDirection for a persistent paragraph setting or the THPDFPara.Direction property for the active paragraph

PDF/UA paragraph semantics

Root := PDF.AddStructureElement('Document', nil);
Paragraph := PDF.BeginTaggedParagraph(Root, 'en-US', 'Accessible text');
PDF.CurrentPage.TextOut(36, 72, 0, WideString('Accessible text'));
PDF.EndTaggedParagraph;

PDF.BeginPaginationArtifact(pasHeader);
PDF.CurrentPage.TextOut(36, 20, 0, WideString('Running header'));
PDF.EndPaginationArtifact;

BeginTaggedParagraph emits a standard /P marked-content sequence with an allocated MCID, page parent-tree wiring, and optional /Lang and /ActualText values

THPDFPaginationArtifactSubtype provides pasHeader, pasFooter, pasWatermark, and pasPageNumber, emitted as /Artifact content with /Type /Pagination and the matching standard subtype