InsertFormObjectFromXObject - TPdf - PDFium Delphi Component

元件: TPdf · 單元: PDFium

將 TPdfXObject 所包裝頁面的一份副本插入此文件目前頁面，並傳回 FPDF_PAGEOBJECT 讓呼叫端可對其定位、縮放、旋轉

Syntax

function InsertFormObjectFromXObject(XObject: TPdfXObject): FPDF_PAGEOBJECT;

Description

InsertFormObjectFromXObject 是 v1.25.0 Form XObject 重複使用 API 的後半部。它接受一個 TPdfXObject 控制代碼（由 CreateXObjectFromPage 建立），並將一個引用該 XObject 的 FPDF_PAGEOBJECT 插入本文件的目前頁面。每次呼叫都會插入新的頁面物件，因此同一個 XObject 可以在目的文件的多個頁面上蓋印多次 — 每個印章都共享底層的頁面內容快取，即使浮水印 / 範本內容繁雜，也能控制檔案大小

傳回的 FPDF_PAGEOBJECT 控制代碼可讓呼叫端呼叫 FPDFPageObj_SetMatrix 或 TPdfMatrix 輔助方法，將印章定位 / 縮放 / 旋轉至頁面上的任意位置。若未明確設定變換，插入的頁面會以 1:1 比例停靠在左下角，這幾乎永遠不是你想要的結果；在呼叫 UpdatePage 之前務必先設定矩陣

失敗時傳回 nil（XObject 為 nil、此 TPdf 未 Active、沒有目前頁面）。插入後，頁面物件由頁面擁有，而非由 XObject 擁有 — 釋放 XObject 並不會使已插入的頁面物件失效

Remarks

目的頁面由本 TPdf 的 PageNumber 決定。請先設定 PageNumber，再呼叫 InsertFormObjectFromXObject
印章定位完成後請呼叫 UpdatePage，讓 PDFium 重新算繪頁面內容串流
將同一個 XObject 蓋印到 N 個頁面會在 N 個頁面內容串流中產生 N 個 FPDF_PAGEOBJECT 引用，全部指向單一 XObject 定義 — 遠比將底層內容複製 N 次便宜
XObject 的存留期可以比目的頁面物件的存留期短；一旦插入，頁面即擁有其引用

Example

uses FPdfMatrix;

var
  PageObj: FPDF_PAGEOBJECT;
  M: TPdfMatrix;
begin
  Pdf1.PageNumber := 3;
  PageObj := Pdf1.InsertFormObjectFromXObject(XObj);
  if PageObj <> nil then
  begin
    M := TPdfMatrix.Create;
    try
      M.Translate(100, 200);
      M.Scale(0.5, 0.5);
      M.Rotate(15);
      FPDFPageObj_SetMatrix(PageObj, M.AsMatrix);
    finally
      M.Free;
    end;
    Pdf1.UpdatePage;
  end;
end;

InsertFormObjectFromXObject 方法

元件: TPdf · 單元: PDFium

Syntax

Description

Remarks

Example

See Also