TPDFlibDynamicComponentSession

Tata letak halaman, paginasi, tipe data

Deskripsi

Mengomposisikan komponen berstatus satu halaman tujuan pada satu waktu tanpa membangun konten untuk halaman berikutnya secara terlebih dahulu Setiap percobaan berjalan pada klon di dalam Form XObject terisolasi dan hanya meng-commit klon setelah konten tervalidasi ditempatkan dengan berhasil Penempatan lanjutan dapat menolak overflow, meng-clip konten berukuran alami, atau mengecilkannya secara proporsional sambil menyelaraskannya dalam slot tujuan Kebijakan paginasi dapat mengizinkan pemecahan normal, menunda fragmen parsial pertama ke region baru, atau mengharuskan seluruh komponen tetap terlihat sebelum meng-commit apa pun Kendala flow-space dapat menolak region yang pendek sebelum memanggil komponen atau mencadangkan tinggi yang cukup setelah fragmen terakhirnya bagi komponen berikutnya Hasil yang ditolak, pemanggilan gambar yang gagal, atau pengecualian callback menghapus halaman sementara, memulihkan halaman yang dipilih pemanggil, dan membiarkan konten tujuan serta status komponen saat ini tidak berubah Instance

TPDFlib yang dipasang tetap milik pemanggil dan harus berumur lebih lama daripada sesi

Deklarasi

const
  PDF_DYNAMIC_COMPONENT_ERROR = 0;
  PDF_DYNAMIC_COMPONENT_MORE = 1;
  PDF_DYNAMIC_COMPONENT_COMPLETE = 2;
  PDF_DYNAMIC_COMPONENT_RETRY = 3;

type
  TPDFlibDynamicPageContext = record
    LibraryInstance: TPDFlib;
    PageNumber: Integer;
    CompositionIndex: Integer;
    DestinationLeft: Double;
    DestinationTop: Double;
    AvailableWidth: Double;
    AvailableHeight: Double;
  end;

  TPDFlibDynamicPageResult = record
    HasContent: Boolean;
    HasMoreContent: Boolean;
    UsedWidth: Double;
    UsedHeight: Double;
  end;

  TPDFlibDynamicOverflowPolicy = (dopReject, dopClip, dopScaleDown);
  TPDFlibDynamicHorizontalAlignment = (dhaLeft, dhaCenter, dhaRight);
  TPDFlibDynamicVerticalAlignment = (dvaTop, dvaCenter, dvaBottom);
  TPDFlibDynamicPaginationPolicy = (dppAllowSplit, dppKeepTogether,
    dppRequireComplete);
  TPDFlibDynamicRetryReason = (drrNone, drrKeepTogether,
    drrRequireComplete, drrMinimumSlotHeight, drrMinimumFollowingHeight);

  TPDFlibDynamicLayoutOptions = record
    ContentWidth: Double;
    ContentHeight: Double;
    OverflowPolicy: TPDFlibDynamicOverflowPolicy;
    HorizontalAlignment: TPDFlibDynamicHorizontalAlignment;
    VerticalAlignment: TPDFlibDynamicVerticalAlignment;
    PaginationPolicy: TPDFlibDynamicPaginationPolicy;
    MinimumSlotHeight: Double;
    MinimumFollowingHeight: Double;
  end;

  TPDFlibDynamicPlacementTransform = record
    M11, M12, M21, M22, MDX, MDY: Double;
  end;

  TPDFlibDynamicPagePlacement = record
    PageNumber: Integer;
    CompositionIndex: Integer;
    Left: Double;
    Top: Double;
    Width: Double;
    Height: Double;
    HasContent: Boolean;
    HasMoreContent: Boolean;
    SourceWidth: Double;
    SourceHeight: Double;
    SlotLeft: Double;
    SlotTop: Double;
    SlotWidth: Double;
    SlotHeight: Double;
    Transform: TPDFlibDynamicPlacementTransform;
    WasClipped: Boolean;
    WasScaled: Boolean;
  end;

  TPDFlibDynamicComponent = class
  public
    function CloneComponent: TPDFlibDynamicComponent; virtual; abstract;
    function Compose(const Context: TPDFlibDynamicPageContext;
      out ComposeResult: TPDFlibDynamicPageResult): Integer; virtual; abstract;
  end;

  TPDFlibDynamicComponentSession = class
  private
    FLibrary: TPDFlib;
    FCompositionCount: Integer;
    FCompleted: Boolean;
    FKeepTogetherRetryPending: Boolean;
    FLastRetryReason: TPDFlibDynamicRetryReason;
    FLastRequiredSlotHeight: Double;
  public
    constructor Create(ALibrary: TPDFlib;
      AComponent: TPDFlibDynamicComponent);
    function AttachComponent(AComponent: TPDFlibDynamicComponent): Integer;
    function Reset: Integer;
    function CloneCurrentComponent: TPDFlibDynamicComponent;
    class function CreateLayoutOptions(ContentWidth, ContentHeight: Double;
      OverflowPolicy: TPDFlibDynamicOverflowPolicy = dopReject;
      HorizontalAlignment: TPDFlibDynamicHorizontalAlignment = dhaLeft;
      VerticalAlignment: TPDFlibDynamicVerticalAlignment = dvaTop;
      PaginationPolicy: TPDFlibDynamicPaginationPolicy = dppAllowSplit;
      MinimumSlotHeight: Double = 0;
      MinimumFollowingHeight: Double = 0):
      TPDFlibDynamicLayoutOptions; static;
    function ComposeNext(Page: Integer; Left, Top, Width, Height: Double;
      out Placement: TPDFlibDynamicPagePlacement): Integer;
    function ComposeNextLayout(Page: Integer; SlotLeft, SlotTop, SlotWidth,
      SlotHeight: Double; const Options: TPDFlibDynamicLayoutOptions;
      out Placement: TPDFlibDynamicPagePlacement): Integer;
    property LibraryInstance: TPDFlib read FLibrary;
    property CompositionCount: Integer read FCompositionCount;
    property Completed: Boolean read FCompleted;
    property KeepTogetherRetryPending: Boolean
      read FKeepTogetherRetryPending;
    property LastRetryReason: TPDFlibDynamicRetryReason read FLastRetryReason;
    property LastRequiredSlotHeight: Double read FLastRequiredSlotHeight;
  end;

Kontrak komponen

CloneComponent mengembalikan salinan independen-pemanggil dari seluruh status paginasi yang dapat diubah
Compose menggambar melalui Context.LibraryInstance dalam koordinat Form lokal yang ukuran tersedianya AvailableWidth kali AvailableHeight
PageNumber mengidentifikasi halaman tujuan meskipun library memilih halaman sementara terisolasi selama callback berjalan
Callback dapat memakai API gambar dan konten tetapi tidak boleh mengubah dokumen, halaman, atau kontainer gambar bersarang
Hasil konten memerlukan nilai UsedWidth dan UsedHeight berhingga positif dalam kanvas konten
Rectangle terpakai dimulai dari koordinat lokal nol dan harus membatasi seluruh konten komponen yang terlihat
Hasil tanpa konten hanya valid ketika HasMoreContent bernilai False dan kedua dimensi terpakai nol
Mengembalikan nol menolak percobaan; pengecualian yang dilemparkan menjalar setelah state sementara dibersihkan

Metode

Create	Memasang library milik pemanggil dan mengklon komponen yang diberikan menjadi snapshot awal dan snapshot saat ini yang independen
AttachComponent	Menggantikan kedua snapshot secara atomik dengan klon komponen milik pemanggil dan membersihkan status penyelesaian
Reset	Memulihkan klon saat ini yang baru dari snapshot awal dan mengatur ulang jumlah komposisi yang berhasil
CloneCurrentComponent	Mengembalikan klon milik pemanggil untuk menginspeksi status komponen ter-commit saat ini
CreateLayoutOptions	Membangun pengaturan kanvas alami, overflow, perataan, paginasi, dan flow-space bertipe untuk penempatan lanjutan
ComposeNext	Mengomposisikan satu slot halaman, memvalidasi dan menempatkan Form XObject-nya, melepas handle capture, dan meng-commit status kerja
ComposeNextLayout	Mengomposisikan pada kanvas alami yang dikonfigurasi, menerapkan kebijakan overflow dan perataan, serta mengembalikan data sumber, slot, dan transform akhir

Overflow dan penempatan

`dopReject`	Menolak konten yang lebih lebar atau lebih tinggi dari slot tanpa mengubah konten tujuan atau status komponen ter-commit
`dopClip`	Mempertahankan skala 1 dan mengiriskan clipping path halaman dengan slot tujuan sebelum memanggil Form XObject
`dopScaleDown`	Memakai rasio lebar atau tinggi yang lebih kecil hanya bila diperlukan dan tidak pernah memperbesar konten

Perataan diresolusikan dari rectangle terpakai yang ditransformasi, sehingga konten ter-clip yang berada di tengah atau di ujung memilih bagian terlihat yang sesuai

Transform[M11 M12 M21 M22 MDX MDY]

SlotLeft melaporkan matriks tata letak logis SlotTop dari koordinat lokal komponen ke koordinat dokumen akhir atas-ke-bawah SlotWidth, SlotHeight,

Kebijakan paginasi

`dppAllowSplit`	Mempertahankan perilaku bawaan dan meng-commit setiap fragmen valid yang callback-nya melaporkan lebih banyak konten
`dppKeepTogether`	Mengembalikan `PDF_DYNAMIC_COMPONENT_RETRY` untuk percobaan pertama yang parsial atau tidak terlihat, lalu mengizinkan pemecahan atau fallback clipping terpilih pada percobaan valid berikutnya untuk fragmen yang sama yang belum di-commit
`dppRequireComplete`	Mengembalikan `PDF_DYNAMIC_COMPONENT_RETRY` sampai callback melaporkan tidak ada konten tersisa dan rectangle terpakai penuh muat di slot atau tetap terlihat melalui pengecilan proporsional

Placement

KeepTogetherRetryPending kosong Reset mengidentifikasi state fallback sekali-pakai dan dibersihkan setelah commit yang berhasil, AttachComponent, atau

Batasan flow-space

`MinimumSlotHeight`	Mengembalikan `PDF_DYNAMIC_COMPONENT_RETRY` sebelum mengklon atau memanggil komponen ketika slot tujuan lebih pendek dari tinggi yang dikonfigurasi
`MinimumFollowingHeight`	Hanya berlaku untuk fragmen konten terakhir dan mengharuskan tinggi teresolusinya ditambah tinggi cadangan berikutnya muat di slot

Retry tinggi-berikutnya membuang percobaan terisolasi sambil mempertahankan fragmen ter-commit sebelumnya, memungkinkan heading, label, atau pengantar pendek berpindah bersama region pertama yang dapat dipakai dari komponen berikutnya

LastRetryReason membedakan retry seluruh-komponen, penyelesaian-ketat, slot-minimum, dan ruang-berikutnya, sedangkan LastRequiredSlotHeight melaporkan tinggi yang diketahui diperlukan untuk kendala flow-space Pemeriksaan slot-minimum berjalan sebelum pengklonan komponen dan capture Form, sehingga region pendek yang ditolak berulang tidak menimbulkan biaya callback komponen atau halaman sementara

Nilai yang dikembalikan

`PDF_DYNAMIC_COMPONENT_ERROR`	Permintaan, callback komponen, geometri hasil, atau penempatan Form gagal dan tidak ada state yang di-commit
`PDF_DYNAMIC_COMPONENT_MORE`	Konten telah di-commit dan komponen meminta slot halaman lain
`PDF_DYNAMIC_COMPONENT_COMPLETE`	Komponen selesai, atau sesi sudah selesai dan tidak ada callback yang dilakukan
`PDF_DYNAMIC_COMPONENT_RETRY`	Kebijakan paginasi atau flow-space terpilih menunda penempatan tanpa meng-commit konten atau state

Contoh

type
  TNumberedPagesComponent = class(TPDFlibDynamicComponent)
  private
    FNextPage: Integer;
    FPageCount: Integer;
  public
    constructor Create(ANextPage, APageCount: Integer);
    function CloneComponent: TPDFlibDynamicComponent; override;
    function Compose(const Context: TPDFlibDynamicPageContext;
      out ComposeResult: TPDFlibDynamicPageResult): Integer; override;
  end;

constructor TNumberedPagesComponent.Create(ANextPage, APageCount: Integer);
begin
  inherited Create;
  FNextPage := ANextPage;
  FPageCount := APageCount;
end;

function TNumberedPagesComponent.CloneComponent: TPDFlibDynamicComponent;
begin
  Result := TNumberedPagesComponent.Create(FNextPage, FPageCount);
end;

function TNumberedPagesComponent.Compose(
  const Context: TPDFlibDynamicPageContext;
  out ComposeResult: TPDFlibDynamicPageResult): Integer;
begin
  Context.LibraryInstance.DrawText(0, 0, IntToStr(FNextPage));
  Inc(FNextPage);
  ComposeResult.HasContent := True;
  ComposeResult.HasMoreContent := FNextPage <= FPageCount;
  ComposeResult.UsedWidth := Context.AvailableWidth;
  ComposeResult.UsedHeight := 24;
  Result := 1;
end;

Template := TNumberedPagesComponent.Create(1, 10);
try
  Session := TPDFlibDynamicComponentSession.Create(PDF, Template);
  try
    repeat
      Status := Session.ComposeNext(PageNumber, 36, 36, 540, 720,
        Placement);
      if Status = PDF_DYNAMIC_COMPONENT_MORE then
        PageNumber := PDF.NewPage;
    until Status <> PDF_DYNAMIC_COMPONENT_MORE;
  finally
    Session.Free;
  end;
finally
  Template.Free;
end;

Lihat juga

BeginFormXObject, ReleaseCapturedPage, ApplyRepeatedPageFragment