TPDFlibDynamicComponentSession

Sayfa düzeni, sayfalandırma, veri türleri

Açıklama

Durum taşıyan bir bileşeni, sonraki sayfaların içeriğini önceden kurmadan her seferinde bir hedef sayfaya işler

Her deneme yalıtılmış bir Form XObject içindeki klon üzerinde yürür ve doğrulanmış içerik başarıyla yerleştirildikten sonra klonu işler

Genişletilmiş yerleştirme taşmayı reddedebilir, doğal boyutlu içeriği kırpabilir veya onu hedef yuvası içinde hizalarken orantılı olarak küçültebilir

Sayfalandırma ilkesi olağan bölmeye izin verebilir, ilk kısmi parçayı taze bir bölgeye erteleyebilir veya herhangi bir şeyi işlemeden önce bileşenin tamamının görünür kalmasını isteyebilir

Akış alanı kısıtları bileşeni çağırmadan önce kısa bir bölgeyi reddedebilir veya son parçasından sonra izleyen bileşen için yeterli yükseklik ayırabilir

Reddedilen bir sonuç, başarısız bir çizim çağrısı veya geri çağrım özel durumu geçici sayfayı kaldırır, çağıranın seçtiği sayfayı onarır ve hem hedef içeriği hem geçerli bileşen durumunu değiştirmeden bırakır

Bağlı TPDFlib örneği çağıranın mülkiyetinde kalır ve oturumdan uzun yaşamak zorundadır

Bildirim

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;

Bileşen sözleşmesi

CloneComponent tüm değiştirilebilir sayfalandırma durumunun arayandan bağımsız bir kopyasını döndürür
Compose, kullanılabilir boyutu Context.LibraryInstance ile AvailableWidth olan yerel Form koordinatlarında AvailableHeight üzerinden çizer
PageNumber, geri çağrı çalışırken kitaplık yalıtılmış geçici bir sayfa seçse bile hedef sayfayı tanımlar
Geri çağrı çizim ve içerik API'lerini kullanabilir ancak belgeleri, sayfaları veya iç içe çizim kapsayıcılarını değiştirmemelidir
İçerik sonuçları, içerik tuvali içinde sonlu pozitif UsedWidth ve UsedHeight değerleri gerektirir
Kullanılan dikdörtgen yerel koordinat sıfırında başlar ve görünür tüm bileşen içeriğini kapsamalıdır
İçeriksiz bir sonuç yalnızca HasMoreContent değeri False olduğunda ve her iki kullanılan boyut da sıfır olduğunda geçerlidir
Sıfır döndürmek denemeyi reddeder; oluşturulan istisnalar geçici durum temizlendikten sonra iletilir

Yöntemler

Create	Arayanın sahibi olduğu bir kitaplığı ekler ve verilen bileşeni bağımsız ilk ve geçerli anlık görüntülere kopyalar
AttachComponent	Arayanın sahibi olduğu bir bileşenin kopyalarıyla her iki anlık görüntüyü atomik olarak değiştirir ve tamamlanma durumunu temizler
Reset	İlk anlık görüntüden yeni bir geçerli kopyayı geri yükler ve başarılı birleştirme sayısını sıfırlar
CloneCurrentComponent	Geçerli kesinleştirilmiş bileşen durumunu incelemek için arayanın sahibi olduğu bir kopyayı döndürür
CreateLayoutOptions	Genişletilmiş yerleşim için tipli doğal tuval, taşma, hizalama, sayfalandırma ve akış alanı ayarlarını kurar
ComposeNext	Tek bir sayfa yuvasını birleştirir, Form XObject'ini doğrulayıp yerleştirir, yakalama tanıtıcısını serbest bırakır ve çalışan durumu kesinleştirir
ComposeNextLayout	Yapılandırılan doğal tuval üzerinde birleştirir, taşma ve hizalama ilkesini uygular ve kaynak, yuva ile son dönüşüm verilerini döndürür

Taşma ve yerleşim

`dopReject`	Hedef içeriği veya işlenmiş bileşen durumunu değiştirmeden, yuvadan daha geniş ya da daha uzun içeriği reddeder
`dopClip`	Ölçeği 1 tutar ve Form XObject'i çağırmadan önce sayfa kırpma yolunu hedef yuvasıyla kesiştirir
`dopScaleDown`	Yalnızca gerektiğinde daha küçük genişlik veya yükseklik oranını kullanır ve içeriği asla büyütmez

Hizalama dönüştürülmüş kullanılan dikdörtgenden çözülür; böylece ortalanmış veya sonu kırpılmış içerik, karşılık gelen görünür bölümü seçer

Transform, bileşen yerel koordinatlarından son yukarıdan aşağıya belge koordinatlarına giden mantıksal düzen matrisi [M11 M12 M21 M22 MDX MDY]'yi bildirir

SlotLeft, SlotTop, SlotWidth ve SlotHeight, kırpma altında son içerik başlangıç noktası dışında kalsa bile çağıranın verdiği bölgeyi korur

Sayfalandırma ilkeleri

`dppAllowSplit`	Varsayılan davranışı korur ve geri çağrımı daha fazla içerik bildiren her geçerli parçayı işler
`dppKeepTogether`	İlk kısmi veya görünmez deneme için `PDF_DYNAMIC_COMPONENT_RETRY` döndürür; sonra aynı işlenmemiş parçanın bir sonraki geçerli denemesinde bölmeye veya seçilen kırpma yedeğine izin verir
`dppRequireComplete`	Geri çağrım kalan içerik kalmadığını bildirene ve tüm kullanılan dikdörtgen ya yuvaya sığana ya orantılı küçültmeyle görünür kalana kadar `PDF_DYNAMIC_COMPONENT_RETRY` döndürür

Yeniden deneme Form XObject denemesini atar, hedef sayfayı, bileşen anlık görüntüsünü, tamamlama bayrağını ve bileşim sayacını korur ve boş bir Placement kaydı döndürür

KeepTogetherRetryPending tek kullanımlık yedek durumunu tanımlar ve başarılı bir işleme ile Reset ya da AttachComponent'ten sonra temizlenir

Akış alanı kısıtları

`MinimumSlotHeight`	Hedef yuvası yapılandırılmış yükseklikten kısaysa bileşeni klonlamadan veya çağırmadan önce `PDF_DYNAMIC_COMPONENT_RETRY` döndürür
`MinimumFollowingHeight`	Yalnızca son bir içerik parçasına uygulanır ve çözümlenmiş yüksekliği artı ayrılmış sonraki yüksekliğin yuvaya sığmasını gerektirir

Sonraki yükseklik yeniden denemesi, daha önce işlenmiş parçaları korurken yalıtılmış denemeyi atar; böylece bir başlık, etiket veya kısa giriş, sonraki bileşenin ilk kullanılabilir bölgesiyle birlikte hareket edebilir

LastRetryReason tüm bileşen, katı tamamlama, en küçük yuva ve sonraki alan yeniden denemelerini ayırt eder; LastRequiredSlotHeight ise akış alanı kısıtları için bilinen gerekli yüksekliği bildirir

En küçük yuva denetimi bileşen klonlamadan ve Form yakalamadan önce çalışır; böylece tekrar tekrar reddedilen kısa bölgeler bileşen geri çağrımı veya geçici sayfa maliyeti doğurmaz

Dönüş değerleri

`PDF_DYNAMIC_COMPONENT_ERROR`	İstek, bileşen geri çağrısı, sonuç geometrisi veya Form yerleşimi başarısız oldu ve hiçbir durum kesinleştirilmedi
`PDF_DYNAMIC_COMPONENT_MORE`	İçerik kesinleştirildi ve bileşen başka bir sayfa yuvası istedi
`PDF_DYNAMIC_COMPONENT_COMPLETE`	Bileşen tamamlandı veya oturum zaten tamamlanmıştı ve geri çağrı yapılmadı
`PDF_DYNAMIC_COMPONENT_RETRY`	Seçilen sayfalandırma veya akış alanı ilkesi, içerik veya durum kesinleştirmeden yerleşimi erteledi

Örnek

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;

Ayrıca bkz.

BeginFormXObject, ReleaseCapturedPage, ApplyRepeatedPageFragment