dxHotPDFExportReportLink

DevExpress ExpressPrinting System adapter (Lib\Addons\DevExpress\dxHotPDFExport.pas)

DevExpress ExpressPrinting System（XtraPrinting / XtraReports / cxGrid printable links 等）PDF export adapter，使用 HotPDF 作為底層 PDF backend，而不是 DevExpress 自己的 dxPSExportToPDF / TdxPSPDFExport emitter。適用於已嵌入 HotPDF，並希望整個應用程式共用單一 PDF backend 的專案dxPSExportToPDF / TdxPSPDFExport emitter. Intended for projects that already embed HotPDF and want a single PDF backend across the whole application.

  TdxHotPDFExportOptions = record

    Title, Author, Subject, Keywords: string;

    PDFVersion : TPDFVersType;  // default pdf17

    Compression: TPDFCompressionLevel;  // default clDefault

    RenderDPI  : Integer;  // default 200

  end;

function dxHotPDFDefaultOptions: TdxHotPDFExportOptions;

File-based entry points:

function dxHotPDFExportReportLinkToFile(

  AReportLink: TBasedxReportLink;

  const AOutputFileName: string;

  const AOptions: TdxHotPDFExportOptions): Boolean; overload;

function dxHotPDFExportReportLinkToFile(

  AReportLink: TBasedxReportLink;

  const AOutputFileName: string): Boolean; overload;

Stream-based entry points:

function dxHotPDFExportReportLinkToStream(

  AReportLink: TBasedxReportLink;

  AOutputStream: TStream;

  const AOptions: TdxHotPDFExportOptions): Boolean; overload;

function dxHotPDFExportReportLinkToStream(

  AReportLink: TBasedxReportLink;

  AOutputStream: TStream): Boolean; overload;

說明

DevExpress 的 printing system 以 TBasedxReportLink 為中心；這個 abstract link 會把 printable component（cxGrid、cxRichEdit、cxScheduler、cxPivotGrid 等）連接到 TdxComponentPrinter。printer / link 會組成頁面，然後公開 protected PaintPage(ACanvas, APageBounds, APageIndex, AContinuousIndex, AZoomFactor) method，將單一頁面繪製到任意 TCanvas

此 adapter 對應 DevExpress 自身 TdxPSPDFReportExportProvider.Build 中的迴圈，但不把 PaintPage 的輸出導入 DevExpress PDF canvas，而是導入 TMetafileCanvas。產生的 metafile 接著交給 HotPDF 的 ShowEnhancedMetafile auto-scaling importer：

1. 呼叫端以準備好的 TBasedxReportLink 呼叫 dxHotPDFExportReportLinkToFile 或 dxHotPDFExportReportLinkToStream

2. The adapter calls AReportLink.RebuildReport to compose pages.TdxComponentPrinter. The printer / link composes pages, then exposes a protected PaintPage(ACanvas, APageBounds, APageIndex, AContinuousIndex, AZoomFactor) method that draws a single page to any TCanvas.

This adapter mirrors the loop in DevExpress's own TdxPSPDFReportExportProvider.Build, but instead of routing PaintPage's output into a DevExpress PDF canvas, it routes it into a TMetafileCanvas. The resulting metafile is then fed to HotPDF's ShowEnhancedMetafile auto-scaling importer:

1. The caller invokes dxHotPDFExportReportLinkToFile or dxHotPDFExportReportLinkToStream with the prepared TBasedxReportLink.

2. The adapter calls AReportLink.RebuildReport to compose pages.

3. For each page index, it asks the link for RenderInfo.GetActualPageRenderInfo, computes the page size in PDF points (using DevExpress's own PointsPerInch / UnitsPerInch ratio), builds a TMetafile at the chosen render DPI, and renders the page through PaintPage(MetaCanvas, ...).

4. A new HotPDF page is added (or the auto-created first page is reused), sized to the computed point dimensions, and the metafile is played via ShowEnhancedMetafile.

5. HotPDF.EndDoc writes the PDF; for the stream overloads, the temp file is then copied into the caller-supplied TStream.

3. 對每個 page index，它會向 link 取得 RenderInfo.GetActualPageRenderInfo，計算 PDF points 中的頁面尺寸（使用 DevExpress 自己的 PointsPerInch / UnitsPerInch ratio），以所選 render DPI 建立 TMetafile，並透過 PaintPage(MetaCanvas, ...) render 頁面

4. 新增一個 HotPDF page（或重用自動建立的第一頁），尺寸設為計算出的 point dimensions，然後透過 ShowEnhancedMetafile 播放 metafile

5. HotPDF.EndDoc 寫出 PDF；對 stream overloads，暫存檔接著會複製到呼叫端提供的 TStreamTitle / Author / Subject / Keywords - 文件中繼資料。Title 為空時,adapter 會退用 AReportLink.ReportTitle.Text,再退用 AReportLink.Name,讓 PDF 永遠有非空標題。

 PDFVersion - 文件應目標的 PDF specification level。預設為 pdf17。

OptionsPDFACompliance 與 PDFXCompliance - 把 HotPDF 的標準合規閘門帶進產生的報告 PDF。在依賴最終合規宣告之前,呼叫端仍需透過一般 HotPDF 工作流程備妥所需的 ICC profile、OutputIntent、標記或印刷前資產。

Title / Author / Subject / Keywords - 檔案 metadata。Title 為空時，adapter 會 fallback 到 AReportLink.ReportTitle.Text，再 fallback 到 AReportLink.Name，因此 PDF 一定有非空 titleCompression - FlateDecode level. Defaults to clDefault.

Compression - FlateDecode level. Defaults to clDefault.

RenderDPI - 透過 TMetafileCanvas rasterising 每頁時使用的 pixel density。值越高，文字與線條越銳利，但 metafile 與 PDF 越大。200（預設值）可提供列印品質結果，且不會產生過大檔案。≤ 0 的值會 clamp 到 200

Typical workflow

dxComponentPrinter1.CurrentLink := cxGridReportLink1;

dxHotPDFExportReportLinkToFile(cxGridReportLink1, 'Grid.pdf');

Or with custom options:

Opts := dxHotPDFDefaultOptions;

Opts.Title := 'Q1 Sales';

Opts.RenderDPI := 300;

dxHotPDFExportReportLinkToFile(cxGridReportLink1, 'Grid.pdf', Opts);

支援的 link families

任何 TBasedxReportLink descendant。這涵蓋 cxGrid、cxRichEdit、cxScheduler、cxPivotGrid，以及任何自同一 base class 衍生的 custom links。adapter 不依賴特定 link type，因為 PaintPage contract 定義在 base 上TBasedxReportLink。涵蓋 cxGrid、cxRichEdit、cxScheduler、cxPivotGrid,以及衍生自同一基礎類別的任何自訂 link。此 adapter 不依賴特定 link 類型,因為 PaintPage 合約定義在基礎類別上。

保留的能力

每個 DevExpress link 家族（cxGrid、cxScheduler、cxRichEdit、cxPivotGrid、自訂 link）輸出的向量與點陣頁面內容。GDI 解析後的文字字串（DevExpress 透過 TCanvas 轉譯文字;中繼檔記錄 GDI 文字呼

Capabilities preserved

每個 DevExpress link family（cxGrid、cxScheduler、cxRichEdit、cxPivotGrid、custom links）輸出的 vector 與 raster page content。GDI-resolved text strings（DevExpress 透過 TCanvas render 文字；metafile 會忠實記錄 GDI text calls）

Limitations of the metafile bridge

由於頁面會擷取為 enhanced metafiles，需要結構資訊的 DevExpress-specific PDF features（interactive AcroForm fields、named destinations、bookmarks / outlines、PDF/A 或 PDF/X conformance gates）不會傳遞。輸出會忠實重現 DevExpress render 的視覺結果，但不是 structured PDFLib\Addons\DevExpress\ and is not part of the main HotPDF*.dpk packages, so the DevExpress ExpressPrinting dependency is only pulled in by projects that opt in to the adapter. A smoke test (smoke_dx_hotpdf.dpr) lives alongside the unit.

請參閱： TfrxHotPDFExport, TQRHotPDFExportFilter, TppHotPDFDevice, THPDFPage.ShowMetafile, Enhanced EMF/WMF Support