Layout Visual Diagnostics

HotPDF can retain bounded layout decisions, detect overlapping placed elements, draw native vector overlays, attach caller-supplied source locations, and publish synchronous preview notifications

Safe defaults

THPDFLayoutDiagnosticOptions.Default retains element paths, while source-location capture, overlap detection, PDF overlays, and live callbacks are disabled by default

No source filename or overlay content enters the generated PDF unless the corresponding option is explicitly enabled

Enable visual diagnostics

Options := THPDFLayoutDiagnosticOptions.Default;
Options.CaptureSourceLocation := True;
Options.DetectOverlaps := True;
Options.DrawOverlays := True;
Options.LivePreview := True;
PDF.LayoutDiagnosticOptions := Options;
PDF.OnLayoutDiagnostic := HandleLayoutDiagnostic;

Element.SetDiagnosticSource('invoice_layout.pas', 73, 9);

SetDiagnosticSource stores an optional file, line, and column on a THPDFLayoutElement; ClearDiagnosticSource removes the mapping

Declarative layout continuations copy the mapping to preserve a stable call site across page splits

Diagnostic records

THPDFLayoutDiagnostic includes ElementPath, RelatedElementPath, SourceFile, SourceLine, and SourceColumn in addition to its page, rectangle, line count, kind, and reason

ldkOverlap identifies an intersection between two successfully placed elements, while ldkOverflow identifies an element that could not fit the supplied bounds

Vector overlays and live preview

Overflow rectangles use a red stroke and overlap rectangles use an orange stroke, with optional labels controlled by ShowOverlayLabels

Overlays are native PDF paths and text rather than raster images

THPDFLayoutDiagnosticEvent receives each retained diagnostic synchronously after optional overlay drawing when LivePreview is enabled

Budgets and statistics

MaxTrackedBounds bounds retained placement rectangles and MaxOverlapComparisons bounds intersection work across the diagnostic interval

THPDFLayoutDiagnosticStatistics reports retained and dropped diagnostics, tracked and dropped bounds, overlap comparisons and findings, overlays drawn, and live notifications