TppHotPDFDevice

ReportBuilder adapter (Lib\Addons\ReportBuilder\ppHotPDFDevice.pas)

ReportBuilder device class，使用 HotPDF 作為底層 PDF backend，而不是 ReportBuilder 自己的 ppPDFDevice。適用於已嵌入 HotPDF，並希望整個應用程式共用單一 PDF backend 的專案ppPDFDevice. Intended for projects that already embed HotPDF and want a single PDF backend across the whole application.

Delphi declaration:

type

  TppHotPDFDevice = class(TppGraphicsDevice)

  public

    class function DeviceName: String; override;

    procedure StartJob; override;

    procedure EndJob; override;

    procedure CancelJob; override;

    procedure SetOutputStream(AStream: TStream);

    property FileName: string;

    property Title, Author, Subject, Keywords: string;

    property PDFVersion: TPDFVersType;

    property Compressed: Boolean;

    property CompressionLevel: TPDFCompressionLevel;

  end;

說明

TppHotPDFDevice 繼承自 TppGraphicsDevice（位於 TppCustomScreenDevice / TppImageDevice 上一層），因此指定給 TppReport.PrinterDevice 或作為 TppPublisher 的 publisher device 使用時，會接入 ReportBuilder 的 device chain。DeviceName 回報為 'HotPDF'。由於 ReportBuilder 的 device registration 透過 ppRptDeviceMap 而非 RegisterComponents 完成，因此沒有 IDE component palette entry；呼叫端需直接建立 TppHotPDFDevice

每個經由 TppGraphicsDevice.ReceivePage 進來的頁面，都會繪製到暫時性的 TMetafileCanvas（在 BeforeRenderPage 建立，在 AfterRenderPage finalise）。擷取到的 TMetafile 接著交給 HotPDF 的 ShowEnhancedMetafile auto-scaling importer：

1. StartJob creates the THotPDF instance, sets metadata, and calls BeginDoc.TppReport.PrinterDevice or used as a publisher device on a TppPublisher. DeviceName is reported as 'HotPDF'. Because device registration in ReportBuilder is done via ppRptDeviceMap rather than RegisterComponents, there is no IDE component palette entry - callers instantiate TppHotPDFDevice directly.

2. BeforeRenderPage creates a TMetafile sized to spWidth x spHeight plus a TMetafileCanvas, and sets it as the inherited Canvas.

3. RenderPage（inherited）走訪 DrawCommands，並透過 GraphicsContext 將它們導向我們的 metafile canvas

4. AfterRenderPage finalises metafile（釋放 canvas），新增尺寸為 mmWidth x mmHeight（轉換為 PDF points）的 HotPDF page，並透過 ShowEnhancedMetafile 播放 metafileStartJob creates the THotPDF instance, sets metadata, and calls BeginDoc.

5. EndJob 呼叫 HotPDF.EndDoc；若輸出是 Stream，則從內部寫出的暫存檔複製 bytesBeforeRenderPage creates a TMetafile sized to spWidth x spHeight plus a TMetafileCanvas, and sets it as the inherited Canvas.

 RenderPage (inherited) walks the DrawCommands and routes them through the GraphicsContext onto our metafile canvas.

屬性AfterRenderPage finalises the metafile (free canvas), adds a new HotPDF page sized to mmWidth x mmHeight (converted to PDF points), then either plays the metafile via ShowEnhancedMetafile or emits supported draw commands natively when RenderMode is hprmNativeDrawCommands.

FileName - target PDF path. Used unless SetOutputStream has installed a stream.

Title / Author / Subject / Keywords - 檔案 metadata。Title 為空時，device 會 fallback 到 FileName，因此 PDF 一定有非空 title

PDFVersion - 檔案應目標的 PDF specification level。預設為 pdf17

Compressed - HotPDF stream compression on (default True). Set False for diagnostic PDFs.SetOutputStream has installed a stream.

Title / Author / Subject / Keywords - document metadata. When Title is empty the device falls back to FileName so the PDF always has a non-empty title.

PDFVersion - the PDF specification level the document should target. Defaults to pdf17.

PDFACompliance and PDFXCompliance - forward HotPDF standards-conformance gates into the generated report PDF. Callers still prepare any required ICC profile, OutputIntent, tagging, or prepress assets through the normal HotPDF workflow before relying on the final conformance claim.

Compressed - HotPDF stream compression on (default True). Set False for diagnostic PDFs.

CompressionLevel - FlateDecode level. Defaults to clDefault.

RenderMode - defaults to hprmPageMetafile for the original visual bridge. Set hprmNativeDrawCommands to map supported ReportBuilder draw commands directly to HotPDF text, vector, image, and URI link operations. Pages containing unsupported commands automatically fall back to the metafile bridge.

SetOutputStream(AStream) - route the PDF bytes into CompressionLevel - FlateDecode level. Defaults to clDefault.

SetOutputStream(AStream) - 將 PDF bytes 導入 AStream，而不是寫入磁碟。請在 report 觸發 StartJob 前呼叫

Typical workflow

Dev := TppHotPDFDevice.Create(nil);

try

  Dev.FileName := 'Report.pdf';

  Dev.Title := 'Monthly Statement';

  Dev.PDFVersion := pdf17;

  ppReport1.DeviceType := 'HotPDF';

  ppReport1.PrinterDevice := Dev;

  ppReport1.Print;

finally

  Dev.Free;

end;

Capabilities preserved

由 ReportBuilder 標準 draw-command pipeline render 的 vector 與 raster page content。GDI-resolved text strings。預設 200 DPI metafile capture（可透過 inherited PixelsPerInch 設定）可提供列印品質輸出，且不會產生過大檔案

 PixelsPerInch) gives print-quality output without enormous files. Native draw-command mode maps common text, shape, line, image, and URI hyperlink commands directly to HotPDF page operations when the page contains only supported commands.

Limitations of the metafile bridge

由於頁面會擷取為 enhanced metafiles，需要結構資訊的 ReportBuilder-specific PDF features（AcroForm fields、named destinations、outlines、PDF/A 或 PDF/X conformance gates）不會傳遞。輸出會忠實重現 ReportBuilder render 的視覺結果，但不是 structured PDF

Packaging note

device 位於 Lib\Addons\ReportBuilder\，且不屬於主要 HotPDF*.dpk packages，因此 ReportBuilder dependency 只會由選用此 device 的專案拉入。smoke test（smoke_pp_hotpdf.dpr）與該 unit 放在同一處

請參閱： TfrxHotPDFExport, TQRHotPDFExportFilter, dxHotPDFExportReportLink, THPDFPage.ShowMetafile, Enhanced EMF/WMF SupportLib\Addons\ReportBuilder\ and is not part of the main HotPDF*.dpk packages, so the ReportBuilder dependency is only pulled in by projects that opt in to the device. A smoke test (smoke_pp_hotpdf.dpr) lives alongside the unit.

See also: TfrxHotPDFExport, TQRHotPDFExportFilter, dxHotPDFExportReportLink, THPDFPage.ShowMetafile, Enhanced EMF/WMF Support