Optional Document Handlers

THPDFDocumentHandlerRegistry selects replaceable handlers by inspected content before weak extension or MIME hints, then converts the selected source into one immutable PDF cache shared by export and rendering

Built-in optional handlers

• XPS and OpenXPS retain fixed-page dimensions and visual order, convert self-closing or property-bearing abbreviated Path geometry to native PDF vectors, preserve attribute and property-element solid brushes, multi-stop LinearGradientBrush and elliptical RadialGradientBrush shading patterns, and fill paths through package JPEG, PNG, TIFF, or JPEG XR ImageBrush resources with TileMode=None
• XPS image fills support absolute or RelativeToBoundingBox Viewbox and Viewport mapping, None, Tile, FlipX, FlipY, and FlipXY tile modes, native path and placement clipping, finite six-parameter Transform attributes or ImageBrush.Transform MatrixTransform elements, brush and path opacity, PNG soft-mask alpha, image DPI, and package-resource caching
• XPS Path.OpacityMask supports solid, multi-stop linear or elliptical radial gradient, and PNG ImageBrush masks, including repeated and reflected image cells; uniform alpha is folded into existing graphics states while variable alpha uses bounded native DeviceGray transparency groups that share shading patterns and image soft-mask streams
• XPS Canvas Opacity and Canvas.OpacityMask composite overlapping descendants once through isolated DeviceRGB Form XObjects instead of attenuating each child independently; uniform mask alpha is folded into the group state, variable gradient or PNG image alpha reuses native soft-mask resources, and nested groups retain transformed clips, resource ownership, and bounded link annotations within limits of 4,096 groups and 16 MiB of captured content per group
• XPS VisualBrush recursively converts inline or resource-backed Canvas, Path, and Glyphs visuals, resolves nested and remote ResourceDictionary scopes, maps an absolute Viewbox to an absolute or relative Viewport, and reuses one bounded PDF Form XObject across direct, tiled, and reflected placements
• XPS Canvas.Clip accepts bounded abbreviated geometry, local or remote StaticResource PathGeometry values, and direct property elements with structured line, Bézier, quadratic, or arc figures, geometry transforms, empty geometry, and EvenOdd or NonZero fill rules; nested clips become native PDF W* or W paths, navigation rectangles are intersected with active transformed clip bounds, parsing is capped at 100,000 numeric values, and malformed or singular clips fail closed before child visuals are painted
• XPS Glyphs accepts at most 65,536 strict Indices mappings, retains one-to-many and many-to-one cluster progression, explicit hundredths-of-em advances, horizontal and vertical offsets, odd BidiLevel reverse progression, solid attribute or property-element fills, opacity, Unicode extraction, and fail-closed malformed-input diagnostics; simple runs use native PDF TJ arrays and large mapping buffers grow with amortised linear cost
• Package FontUri resources support TrueType and OpenType programs, TTC member fragments, and XPS GUID-obfuscated fonts; exact glyph IDs, cmap-derived runs, clusters, advances, offsets, RTL origins, font-resource reuse, embedding permissions, optional subsetting, and ToUnicode extraction maps remain native PDF font data without GDI substitution
• XPS FixedPage.NavigateUri on transformed Path and Glyphs visuals becomes a native PDF link annotation with geometry- or metric-derived bounds; HTTP, HTTPS, and mail links remain URI actions, while package-relative pages and percent-decoded LinkTarget fragments become forward or backward GoTo actions after every page is available
• A Canvas FixedPage.NavigateUri becomes the inherited target of every descendant Path, Glyphs, or nested Canvas visual until a descendant supplies its own URI; scoped targets restore after nested overrides, follow each visual's geometry and transform, remain constrained by active Canvas clips, survive isolated opacity-group capture, and stay suppressed inside reusable VisualBrush Forms
• Navigation is capped at 65,536 links with 8,192 characters per URI, checked for cancellation while publishing, suppressed during reusable VisualBrush capture, and rejected for control characters, unsafe schemes, missing targets, or path and fragment mismatches
• Non-standard RelativeTransform, unresolved matrix resources, Repeat or Reflect gradient spread, non-sRGB interpolation, variable-alpha paint brushes, color conversion, image strokes, relative VisualBrush viewboxes, style simulation, sideways glyphs, and advanced stroke properties remain explicit diagnostics
• EPUB resolves container.xml, manifest, and spine order, then uses the bounded HTML5 paged-media importer with callback-only package resources
• CBZ recognizes supported image entries, applies deterministic natural filename order, and creates one page per image at the configured image DPI

Budgets and failure isolation

One validated ZIP central-directory scan enforces entry, compressed-byte, expanded-byte, per-entry, duplicate-path, unsafe-path, and compression-ratio limits before conversion

Classic PKZIP ZipCrypto entries can request credentials through ArchivePasswordCallback; the callback receives the source name, entry name, and one-based attempt number, while MaxPasswordAttempts bounds retries from 1 through 16

Credentials and partially decoded entry bytes remain in memory and are cleared between attempts, cancellation is checked before and after every callback, and missing callbacks, declined credentials, exhausted retries, or unsupported encryption fail closed

ZipCrypto is legacy password protection rather than modern authenticated encryption, and non-ASCII password byte conventions can vary between ZIP producers

Password-protected entries need Delphi 12 or later, whose System.Zip exposes the decryption hook; built with an earlier Delphi version, the handlers still read unencrypted entries but reject encrypted ones as unsupported before ArchivePasswordCallback is called

Entries whose sizes or offsets need ZIP64 fields require Delphi 11 or later; earlier Delphi versions reject them as unsupported

Resource, reflow, page, pixel, DPI, output, and cancellation limits remain active throughout conversion and rendering, while failed output publication restores a seekable destination stream

Registration and use

var
  Registry: THPDFDocumentHandlerRegistry;
  Options: THPDFDocumentHandlerOptions;
  Handled: IHPDFHandledDocument;
  Info: THPDFDocumentHandlerInfo;
begin
  Registry:= THPDFDocumentHandlerRegistry.Create;
  try
    Registry.RegisterStandardHandlers;
    Options:= THPDFDocumentHandlerOptions.Default;
    Options.ArchivePasswordCallback:= SupplyArchivePassword;
    if Registry.OpenFromFile('book.epub', '', Options, Handled, Info) then
      Handled.WritePDF(OutputStream, Options, Info);
  finally
    Registry.Free;
  end;
end;

Related APIs

• THPDFDocumentHandlerRegistry
• IHPDFDocumentHandler
• IHPDFHandledDocument
• THPDFDocumentHandlerOptions
• HTML5 Paged-Media Import