pdfImportPage

Purpose — Import one source page (1-based PageNum).

Description — Two modes, selected by the ifImportAsPage import flag:

• Template mode (default) — the page's content, resources, and MediaBox become a form XObject registered as a template. Nothing appears in the output until the template is placed with pdfPlaceTemplate — one template can be placed many times (N-up, letterheads, watermark underlays). Placement also carries the source page's non-widget annotations across (rect-transformed) when ifAllAnnots is set.
• Page mode (ifImportAsPage) — the page is appended as a first-class, editable /Type /Page: content stream, resources, MediaBox, non-zero origin, /CropBox//BleedBox//TrimBox//ArtBox, and /Rotate are all preserved. The imported page becomes the current page — you may draw additional content on it before pdfEndPage. AcroForm widget fields come across when ifAllAnnots is set, and structure-tree elements are re-anchored automatically for tagged sources.

int32_t __stdcall pdfImportPage(PPDF IPDF, uint32_t PageNum);

function pdfImportPage(const IPDF: PPDF; PageNum: Cardinal): Integer; stdcall; external 'LumasPdf.dll';

Return value — Template mode: the template handle (> 0). Page mode: the 1-based destination page number. 0 on failure (no import source, PageNum out of 1..pageCount).

Common mistakes — In template mode, forgetting pdfPlaceTemplate — the import alone draws nothing. In page mode, forgetting that the imported page is left open: call pdfEndPage before importing the next page.

Example — stamp an existing page and keep it editable (Delphi)

var
  Pdf: PPDF; Fnt: Integer;
begin
  Pdf := pdfNewPDF;
  try
    if not pdfCreateNewPDFW(Pdf, 'stamped.pdf') then Abort;
    pdfSetImportFlags(Pdf, ifImportAll or ifImportAsPage);
    if pdfOpenImportFileW(Pdf, 'source.pdf', 0, nil) < 0 then Abort;
    if pdfImportPage(Pdf, 1) = 0 then Abort;      // page 1 is now open + current
    Fnt := pdfSetFontW(Pdf, 'Helvetica', fsNone, 24, True, cp1252);
    if Fnt <= 0 then Abort;   // 0 = failure; handles are 1-based
    pdfWriteTextW(Pdf, 50, 50, 'COPY');           // draws ON the imported page
    if not pdfEndPage(Pdf) then Abort;
    if not pdfCloseFile(Pdf) then Abort;
  finally
    pdfDeletePDF(Pdf);
  end;
end;

C# (P/Invoke)

public static extern int pdfImportPage(IntPtr IPDF, uint PageNum);