Advanced rendering and export

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

Custom graphics backends

TXLSGraphicsTextAlign defines left, centre, 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 having 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 turn up 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 one 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 handing over ownership

Classic and XLSX HTML entry points capture xlsrgbHtml; TXLSHTMLExport.RenderGeometry exposes the most recent Classic snapshot, whilst 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 the configured screen scaling before emitting a fixed CSS pixel length; point and pixel conversion uses the same captured measurement DPI

Each operation keeps 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 own 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 colour so custom painters can match Excel's own header rendering

Merged cells in native pagination

TXLSPaginationModel.RenderPageToBackend resolves a merged range back to its original anchor and paints one visible rectangle per page fragment; covered cells do not emit duplicate text or internal gridlines

XLSX fragments share the anchor's fill, alignment, wrapping, font, and conditional-format evaluation, whilst explicit outer border segments remain visible and internal merge borders are suppressed; Classic fragments share the anchor's text and solid fill through the existing Classic text painter

A print area or page break can clip a merged range, and every visible fragment keeps the original anchor even when that anchor lies outside the printed area; hidden rows and columns contribute zero extent, and repeated print-title fragments use the same anchor policy

Merging does not force a range onto one page, expand the print area, or alter stored row heights and column widths; pagination keeps the existing page setup and clips each fragment to its logical page

Worksheet background rendering

The workbook viewer displays valid Classic and XLSX worksheet backgrounds as repeating tiles behind unfilled cells, whilst 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 keep 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 hangs on to one decoded image per worksheet, resource generation, backend, DPI, and colour mode for the render session; BackgroundDecodeCount exposes the decode total for diagnostics, whilst 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 handles 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 unless told otherwise; set ExportObjectPlaceholders on the corresponding exporter or HTML options to ask for boxes without image decoding or chart-scene construction

xlsodmHideAll is an earlier global gate that blocks 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

Refreshing chart source data

XLSX chart serialisation and shared chart rendering resolve local series caches against the current workbook generation, so source-cell edits, recalculation, and visibility changes refresh values, categories, bubble sizes, and range-linked series names before output

Ordinary source ranges must be a single row or column of local A1 references; quoted worksheet names are supported, and an unqualified range resolves against the chart's owning worksheet; hierarchical category levels keep their separate rectangular-range resolver

Category text uses formatted cell text, numeric caches hold empty point slots for blanks and nonnumeric text, error cells keep their displayed error literals, and dates use the workbook's 1900 or 1904 serial system; PlotVisibleOnly decides whether hidden source rows and columns are omitted

Imported or manually populated caches are kept when a local source has never been materialised, whilst caches already managed from local cells clear stale points after deletion; TXLSXChartSeries.RefreshDataCaches explicitly refreshes resolvable local sources, including an empty source range

External workbook references and unsupported reference expressions keep their stored caches; cache refresh does not open external files or make network requests

Calendar-aware chart date axes

TXLSXChartSeries.ResolveDataCaches resolves supported local series sources for the current generation, and RefreshDataCaches asks for an explicit refresh even when an empty source has no cell history

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

BaseTimeUnit controls day, month, or year normalisation, whilst MajorUnit, MinorUnit, MajorTimeUnit, and MinorTimeUnit advance ticks by calendar units; month and year intervals therefore stay 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, whilst XLSX HTML uses the shared calendar arithmetic for its inline chart SVG

Standalone PDF writer

TXLSPDFWriter creates PDF documents that do not come 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 bottom-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, whilst PageWidth and PageHeight report the current page box in points

SVG export

TXLSSvgExport provides seven SaveAsSVG overloads covering 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, whilst 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 builds 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, whilst 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 whilst 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 artefact 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 artefacts

Each visible informative picture instance gets 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 artefacts, 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 get validated before the output stream is committed

TXLSPDFExport.ExportCommentsAsAnnotations places Unicode author and comment text on originating cell rectangles whilst 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 take 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 leaves 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 penalising 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, colours, 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 follow the same hierarchy model and AutoSheetBookmarks toggles their generation

BeforeNewPage can adjust each page box, whilst 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, whilst CertificationPolicy optionally creates a DocMDP certification signature allowing no changes, form filling and signing, or form filling, signing, and annotations; PDF/A-1 does not allow 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 hands back host-created CMS data, so HotXLS never needs a private key

TXLSPDFExport.Signature attaches the signature configuration and PDF/A-3 profiles can include validated associated files through AddAttachment, which queues a TXLSPDFAttachment; the detailed overload takes a Unicode display name, MIME type, description, modification time, payload, and a TXLSPDFAttachmentRelationship value of Source, Data, Alternative, Supplement, or Unspecified, whilst 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, whilst invalid images fail before signing

The IXLSPDFAttachmentSource overload stays 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 rather than 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 takes the ByteRange and signature contents patches, an incremental SHA-256 over the two covered ranges, and one single forward copy

PDF/A-3 output writes each associated file into both the EmbeddedFiles name tree and the 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 turn away 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 keeps 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 later measurement and drawing

Font embedding policy

TXLSPDFExport.FontEmbedding (type TXLSPDFFontEmbedding) selects automatic embedding, required subsetting, the complete font programme, 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 refuses map-only output

OnFontEmbed fires once per Unicode face before its metrics, character map, shaping, and glyph identifiers get resolved; setting Handled accepts the returned per-font mode and optional replacement bytes, whilst 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, whilst 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 one 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