Advanced rendering and export

PDF, SVG, bitmap, metafile, preview, and print paths share one pagination model and backend-neutral geometry while retaining format-specific encoders

Custom graphics backends

TXLSGraphicsTextAlign defines left, center, and right text alignment for TXLSGraphicsBackend; styled drawing calls take the remaining shared enums — font styles (TXLSGraphicsFontStyles), line caps (TXLSGraphicsLineCap), dash patterns (TXLSGraphicsLineDash), and vertical text alignment (TXLSGraphicsTextVAlign)

Implementations receive coordinates in points, resolved text and image effects, clipping, and page-local drawing placement without needing to repeat workbook layout logic. Each drawing on a logical page arrives as a TXLSPageDrawingPlacement record whose Kind (TXLSPageDrawingKind: xpdkImage, xpdkChart, xpdkTextBox, xpdkShape, xpdkControl) tells the backend what it is painting; worksheet-background tiles arrive as decoded TXLSSheetBackgroundRenderData

Operation-owned render geometry

TXLSPaginationModel.RenderBackend selects the backend identity captured by the next Build call, and RenderGeometry exposes the resulting immutable calibration, workbook generation, backend, and bounded metric-cache state; the active render session travels as a TXLSRenderSession handle and the colour policy is a TXLSRenderColorMode (xlsrcColor or xlsrcMonochrome)

PDF models use xlsrgbPdf, SVG uses xlsrgbSvg, page images use xlsrgbBitmap, printing and print-preview models use xlsrgbPrintPreview, and TXLSWorkbookViewer uses xlsrgbViewer; PaginationModel on SVG, image, print, and viewer components exposes the active model for diagnostics without transferring ownership

Classic and XLSX HTML entry points capture xlsrgbHtml; TXLSHTMLExport.RenderGeometry exposes the most recent Classic snapshot, while TXLSXHtmlExportSession.RenderGeometry exposes the snapshot retained across every sheet in an incremental export

HTML column output converts the workbook character-width model through the Normal font maximum digit width and configured screen scaling before emitting a fixed CSS pixel length; point and pixel conversion uses the same captured measurement DPI

Each operation retains its captured calibration even if the workbook changes later, and rendering never writes worksheet row heights or column widths. Pagination builds pages from TXLSLogicalPage objects whose drawings, orientation (TXLSPageOrientation: xpoPortrait or xpoLandscape), and comment placement (TXLSPrintComments: xpcNone or xpcAtEnd) come from the resolved page setup

A logical page exposes everything a backend or callback needs: identity (DocumentPageNumber, SheetPageNumber, SheetName, the owning ClassicWorksheet or XlsxWorksheet), geometry (PageWidth, PageHeight, Scale, and the LeftMargin, RightMargin, TopMargin, BottomMargin, HeaderMargin, and FooterMargin values), the data rectangle (DataFirstRow, DataLastRow, DataFirstCol, DataLastCol) with print titles (RepeatFirstRow, RepeatLastRow, RepeatFirstCol, RepeatLastCol), background placement (BackgroundOffsetX, BackgroundOffsetY), gridline output (PrintGridlines, GridlineColor), the six header and footer band texts (LeftHeader, CenterHeader, RightHeader, LeftFooter, CenterFooter, RightFooter), and the page's row and column skeletons (RowCount with Rows and RowEdges, ColumnCount with Columns and ColumnEdges) plus its drawing list (DrawingCount and Drawings). ExpandHeaderFooter resolves header and footer format codes against the page, and ExpandHeaderFooterStyled additionally reports the leading point size and color so custom painters can match Excel's own header rendering

Worksheet background rendering

The workbook viewer displays valid Classic and XLSX worksheet backgrounds as repeating tiles behind unfilled cells, while explicit and conditional cell fills remain above the background

TXLSPaginationModel, TXLSSvgExport, TXLSPageImageExporter, TXLSPrintDocument, TXLSPDFExport, TXLSHTMLExport, TXLSXHtmlExportOptions, and TXLSWorkbookViewer expose ExportSheetBackgroundImages; the default is False for print, preview, metafile, PDF, SVG, bitmap, and HTML output. Worksheets store their payload with a TXLSSheetBackgroundFormat image format, and the decoded bytes travel as a TXLSSheetBackgroundResource keyed by generation, DPI, and colour mode

Enabled paginated output anchors the tile phase to worksheet coordinates across page boundaries and retains one decoded image per worksheet, resource generation, backend, DPI, and colour mode for the render session; BackgroundDecodeCount exposes the decode total for diagnostics, while corrupt payloads are skipped with a workbook diagnostic. The active TXLSRenderSession manages that shared cache itself: AcquireBackground fetches (or decodes once) the tiled TXLSSheetBackgroundRenderData for a worksheet, DrawTiledBackground paints it across a clipped page region, and DecodeCount reports how many payloads were decoded so far

Workbook object display policy

ObjectDisplayMode selects xlsodmShowAll, xlsodmShowPlaceholders, or xlsodmHideAll for both Classic XLS and XLSX workbooks; the viewer consumes all three states and uses low-cost type, name, text, and alternative-text boxes for placeholder mode

PDF, SVG, bitmap, physical-print, and XLSX HTML exporters treat placeholder mode as full-object output by default; set ExportObjectPlaceholders on the corresponding exporter or HTML options to request boxes without image decoding or chart-scene construction

xlsodmHideAll is an earlier global gate that prevents drawing collection, object-driven range expansion, hit testing, and media rendering; worksheet backgrounds, conditional-format icons, header or footer pictures, cells, and exporter-specific print-object filters remain independent

Calendar-aware chart date axes

XLSX charts whose category axis uses xlsxAxisDate map every valid category through the workbook's 1900 or 1904 serial-date system and retain the real distance between sparse dates instead of assigning equal point slots

BaseTimeUnit controls day, month, or year normalization, while MajorUnit, MinorUnit, MajorTimeUnit, and MinorTimeUnit advance ticks by calendar units; month and year intervals therefore remain aligned across unequal month lengths and leap years

The same bounded tick collection supplies coordinates, labels, ticks, and requested gridlines to pagination-based PDF, SVG, bitmap, preview, print, and viewer output, while XLSX HTML uses the shared calendar arithmetic for its inline chart SVG

Standalone PDF writer

TXLSPDFWriter creates PDF documents that do not originate from a workbook, such as invoices, tickets, labels, and overlay forms; BeginDoc sets a point-precise page box, NewPage closes the current page, and SaveToStream or SaveToFile finishes the document

Drawing methods use PDF points from the lower-left corner and library colours in $00BBGGRR or $AABBGGRR form; available primitives cover FillRectangle, StrokeRectangle, ClipRectangle, MeasureText, SaveGraphicsState, and RestoreGraphicsState for filled and stroked rectangles, lines, ellipses, styled text with exact width measurement, affine transforms, rectangular clipping, and explicit save or restore of graphics state, while PageWidth and PageHeight report the current page box in points

SVG export

TXLSSvgExport provides seven SaveAsSVG overloads for classic and XLSX ranges, worksheets, workbooks, and prepared logical pages, plus named-object output where supported

UseWorksheetPageSetup, Orientation, and Margin use the same page setup decisions as PDF and preview output

TXLSSvgExport.PrintComments (type TXLSPrintComments) selects how cell comments are emitted for paginated SVG output; when set to xpcAtEnd, the sheet's last page appends a comment listing (cell address, author, and text) below the data area, while xpcNone omits comments

ExportPages sends one complete SVG document at a time through OnPage, reports committed page count through ExportedPageCount, and stops before generating later pages when the callback cancels; IdPrefix creates deterministic document and page namespaces for clip paths, filters, patterns, and shared resources

HyperlinkMode (type TXLSSvgHyperlinkMode) with xshmSafe adds clipped transparent hit regions after visual content; allowed external schemes are HTTP, HTTPS, mail, FTP, and relative links, while active, local, UNC, and control-character targets are omitted; LinksInNewWindow adds noopener noreferrer protection and ScreenTips become SVG titles

Incremental PNG, JPEG, and multipage TIFF output

TXLSPageImageFormat selects PNG or JPEG output and TXLSPageImageExporter keeps one pagination session alive while releasing each completed bitmap promptly

Tagged PDF and PDF/A

TXLSPDFExport.TagMode enables automatic document, table, row, header-cell, data-cell, and informative-picture structure with dense page-local marked-content identifiers, exact parent-tree mappings, merged-cell spans, and artifact isolation; print-title rows and table header rows become semantic header cells, XLSX pictures with non-empty AltText become independent Figure elements with Unicode alternative text, and pictures without alternative text remain decorative artifacts

Each visible informative picture instance receives its own Figure element and marked-content identifier even when equal image payloads share one PDF XObject; AltTextTitle does not replace missing alternative text, charts remain artifacts, and this focused structure support does not claim complete PDF/UA conformance

TXLSPDFExport.PDFAProfile selects PDF/A-1, PDF/A-2, or PDF/A-3 at conformance level a or b; incompatible encryption, fonts, attachments, transparency, signatures, and metadata are validated before the output stream is committed

TXLSPDFExport.ExportCommentsAsAnnotations places Unicode author and comment text on originating cell rectangles while the traditional comments-at-end output remains independently configurable

UsePDFA is the compatibility switch for PDF/A-1b, while UseXRefStream selects cross-reference streams where the chosen profile permits them

Page geometry and selection

The six CalculatePageCount overloads accept classic and XLSX ranges, worksheets, or workbooks without building PDF objects

PaperWidth and PaperHeight override paper dimensions in points, LastPage closes the one-based output interval, Orientation (type TXLSPDFOrientation) selects portrait or landscape output, HidePrintObjects (a set of TXLSPDFHidePrintObject: xlsPdfHideHeaders, xlsPdfHideFooters) suppresses selected header or footer bands, and PageLayout (type TXLSPDFPageLayout) sets the initial viewer page arrangement

PDF page mode and open action

TXLSPDFExport.PageMode (type TXLSPDFPageMode) sets how a PDF viewer arranges panels when the document opens, through xlsPdfModeDefault, xlsPdfModeUseOutlines, xlsPdfModeUseThumbs, xlsPdfModeFullScreen, xlsPdfModeUseOC, and xlsPdfModeUseAttachments

OpenAction (type TXLSPDFOpenAction) selects the initial viewer behaviour with xlsPdfOpenNone, xlsPdfOpenPage, or xlsPdfOpenOutlines. For xlsPdfOpenPage, OpenActionPage is the one-based target page (clamped to the page count) and OpenActionZoom is the initial magnification factor, where 0 keeps the viewer default zoom or fit

Shared adaptive vector geometry

XLSBuildEllipticArcCubics converts an elliptical arc into cubic Bezier segments by recursively enforcing a caller-selected flatness bound; PDF, SVG, and bitmap rendering use this shared geometry so large or highly eccentric arcs receive more segments without penalizing simple arcs

XLSDecodeVectorScene validates EMF and WMF headers, record alignment and sizes, declared totals, exact EOF placement, and resource limits without calling platform metafile playback; the native whitelist replays device-context state stacks with save and restore, window and viewport mapping combined with world transforms, pen, brush, and extended-pen object tables including stock objects, rectangles, ellipses, line chains, polygons, polylines, and Bézier curves with dash styles, path brackets with fill, stroke, and combined stroke-and-fill passes, rounded rectangles, arcs, chords, pies, and angle arcs through exact arc-to-Bézier conversion, region fills and frames from bounded RGNDATA rectangles, bounded text runs with fonts, colors, and alignment, and restricted stretch-DIB images re-encoded as PNG through Canvas and SVG, rejects escape records, and leaves clipping and private records to the existing bounded fallback

PDF outlines and page callbacks

PDF outlines live in the Bookmarks collection (type TXLSPDFBookmarks): Add and AddForSheet append entries, Delete removes one, and Count with Items enumerate the tree. Each TXLSPDFBookmark entry supports parent and child entries (Children), sibling chains, Unicode titles, colours (Color), a PageNumber target, the source SheetName for worksheet bookmarks, and bold or italic flags (set of TXLSPDFBookmarkStyle: xlsPdfBookmarkBold, xlsPdfBookmarkItalic), plus expanded or collapsed descendants; automatic worksheet bookmarks use the same hierarchy model and AutoSheetBookmarks toggles their generation

BeforeNewPage can adjust each page box, while BeforeGeneratePage and AfterGeneratePage draw background or overlay content through the public page helpers AppendPageContent, FillPageRectangle, StrokePageRectangle, and DrawPageText

Signatures and attachments

TXLSPDFSignature configures visible or invisible signature fields, while CertificationPolicy optionally creates a DocMDP certification signature permitting no changes, form filling and signing, or form filling, signing, and annotations; PDF/A-1 does not permit this PDF 1.5 feature and is rejected before output is committed

TXLSPDFCertificationPolicy provides xlsPdfApprovalSignature, xlsPdfCertifyNoChanges, xlsPdfCertifyFormFillingAndSigning, and xlsPdfCertifyFormFillingSigningAndAnnotations for selecting the signature policy explicitly

A TXLSPDFSignDigestEvent receives the digest and returns host-created CMS data, so HotXLS never needs a private key

TXLSPDFExport.Signature attaches the signature configuration and PDF/A-3 profiles may include validated associated files through AddAttachment, which queues a TXLSPDFAttachment; the detailed overload accepts a Unicode display name, MIME type, description, modification time, payload, and a TXLSPDFAttachmentRelationship value of Source, Data, Alternative, Supplement, or Unspecified, while AttachmentCount reports the queued total and AttachmentDuplicatePolicy (type TXLSPDFAttachmentDuplicatePolicy) selects how equal names are handled

TXLSPDFSignature.ImageData, ImageFormat, and ImageFit (type TXLSPDFSignatureImageFit: contain, cover, or stretch) place a PNG in the normal appearance Form before the byte range is frozen; contain, cover, and stretch modes share the document image cache, while invalid images fail before signing

The IXLSPDFAttachmentSource overload remains lazy until save, invokes each source once per save, and spools at most 256 MiB before the EmbeddedFile object is created so provider failures leave the destination transaction unchanged

Final assembly writes objects sequentially to the destination instead of building one whole-document string: unsigned exports stream straight into forward-only streams, each EmbeddedFile references its byte size through an indirect /Length object emitted after the payload, and provider bytes copy from the spool in fixed chunks; signed exports assemble into a bounded document spool that receives the ByteRange and signature contents patches, an incremental SHA-256 over the two covered ranges, and a single forward copy

PDF/A-3 output writes each associated file into both the EmbeddedFiles name tree and catalog AF array, with a Unicode UF name, escaped MIME PDF Name, AFRelationship, byte size, optional modification date, and optional description; PDF/A-1 and PDF/A-2 reject queued attachments before committing output

Document metadata

DocumentTitle, DocumentAuthor, DocumentSubject, DocumentKeywords, and DocumentFileName populate the PDF information and metadata dictionaries

Font fallback

TXLSPDFExport.SetFontFallbackChain, AddFontFallback, and ClearFontFallbackChains configure source-family and style-specific fallback tiers; LoadedFallbackFontCount exposes the cached face count and FontFallbackSelectionCacheCount the number of cached per-selection fallback decisions, both for diagnostics

TXLSPDFExport.FontSize sets the default text size in points, with 9 as the default

Fallback selection uses glyph coverage and preserves Unicode mappings, supplementary scalars, grapheme clusters, shaping clusters, and standalone TTC faces

OnGetFontDirectories can return one or more semicolon-separated font directories for a requested family and style; accepted directories are searched recursively once, indexed by internal family/style metadata, and cached for subsequent measurement and drawing

Font embedding policy

TXLSPDFExport.FontEmbedding (type TXLSPDFFontEmbedding) selects automatic embedding, required subsetting, the complete font program, or map-only output through xlsPdfFontEmbedAuto, xlsPdfFontEmbedSubset, xlsPdfFontEmbedFull, and xlsPdfFontEmbedNone; required subsetting fails atomically when a valid subset cannot be produced, TTC faces are converted to standalone fonts, and PDF/A rejects map-only output

OnFontEmbed fires once per Unicode face before its metrics, character map, shaping, and glyph identifiers are resolved; setting Handled accepts the returned per-font mode and optional replacement bytes, while leaving it false retains the document policy and original face

Standalone OpenType fonts with CFF outlines embed through FontFile3 with an OpenType stream and a CIDFontType0 descendant; automatic and full modes retain the complete program, while required CFF subsetting fails atomically because it cannot preserve a valid subset

Embedded fonts carrying OpenType GPOS or legacy kern data use positioned glyph advances for simple and complex text, so measurement, wrapping, alignment, and emitted glyph positions share the same kerning result

Progress and cancellation

TXLSPDFExport.OnProgress and OnProgressEx report begin, page, and end phases; Cancel requests cancellation, and Aborted reports the final state without committing a partial stream

See also

• TXLSPaginationModel
• SaveAsPDF
• Advanced workbook workflows