TPDFlibDynamicComponentSession

Oldalelrendezés, lapozás, adattípusok

Leírás

Állapotot hordozó komponenst egy-egy céloldalra komponál anélkül, hogy a későbbi oldalak tartalmát előre megépítené

Minden kísérlet klónon fut izolált Form XObjecten belül, és csak sikeres, validált tartalomelhelyezés után vállalja a klónt

A kiterjesztett elhelyezés elutasíthatja a túlcsordulást, levághatja a természetes méretű tartalmat, vagy arányosan lecskálázhatja, miközben céllyukon belül igazítja

A lapozási házirend engedhet normális felosztást, friss régióba halaszthatja az első részleges darabot, vagy megkövetelheti, hogy a teljes komponens látható maradjon, mielőtt bármit vállalna

A folyami térbeli korlátok elutasíthatnak egy rövid régiót a komponens meghívása előtt, vagy elegendő magasságot foglalhatnak az utolsó darabja után egy következő komponensnek

Elutasított eredmény, sikertelen rajzolási hívás vagy visszahívási kivétel törli az ideiglenes oldalt, visszaállítja a hívó által kiválasztott oldalt, és a céltartalmat és az aktuális komponensállapotot is változatlanul hagyja

TPDFlib példány a hívó tulajdonában marad, és túl kell élnie a munkamenetet

Deklaráció

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;

Komponensszerződés

A CloneComponent a hívótól független másolatot ad vissza az összes módosítható lapszámolási állapotról
A Compose a Context.LibraryInstance útján rajzol helyi Form koordinátákban, amelyek rendelkezésre álló mérete AvailableWidth széles és AvailableHeight magas
A PageNumber azonosítja a céloldalt, annak ellenére, hogy a könyvtár a visszahívás futása alatt izolált ideiglenes oldalt választ ki
A visszahívás használhatja a rajzolási és tartalmi API-kat, de nem módosíthat dokumentumokat, oldalakat vagy egymásba ágyazott rajzolási tárolókat
A tartalmi eredményekhez véges, pozitív UsedWidth és UsedHeight értékek szükségesek a tartalmi vásznon belül
A felhasznált téglalap a nulla helyi koordinátán indul, és minden látható komponenstartalmat körül kell határolnia
A tartalom nélküli eredmény csak akkor érvényes, ha a HasMoreContent False, és mindkét felhasznált dimenzió nulla
A nulla visszaadása elutasítja a kísérletet; a kiváltott kivételek az ideiglenes állapot törlése után terjednek tovább

Metódusok

Create	Csatol egy hívói tulajdonú könyvtárat, és a szolgáltatott komponenst független kiinduló és aktuális pillanatképekbe klónozza
AttachComponent	Atomikusan cseréli mindkét pillanatképet egy hívói tulajdonú komponens klónjaira, és törli a befejezettségi állapotot
Reset	Új aktuális klónt állít vissza a kiinduló pillanatképből, és nullára állítja a sikeres összeállítások számát
CloneCurrentComponent	Hívói tulajdonú klónt ad vissza az aktuális, véglegesített komponensállapot megvizsgálásához
CreateLayoutOptions	Típusos természetes vászon-, túlcsordulási, igazítási, lapszámolási és folyamterületi beállításokat épít a kiterjesztett elhelyezéshez
ComposeNext	Egy oldalhelyet állít össze, ellenőrzi és elhelyezi a Form XObjectet, felszabadítja a rögzítési handle-t, és véglegesíti a munkaállapotot
ComposeNextLayout	A konfigurált természetes vásznon állít össze, alkalmazza a túlcsordulási és igazítási szabályzatot, majd forrás-, hely- és végső transzformációs adatokat ad vissza

Túlcsordulás és elhelyezés

`dopReject`	Elutasítja a helynél szélesebb vagy magasabb tartalmat cél tartalom vagy véglegesített komponensállapot módosítása nélkül
`dopClip`	Az 1-es skálát megtartja, és a Form XObject meghívása előtt az oldal vágóútvonalát a célhellyel metszeti kapcsolatba hozza
`dopScaleDown`	Csak szükség esetén használja a kisebb szélességi vagy magassági arányt, és soha nem nagyítja a tartalmat

Az igazítás az átalakított, felhasznált téglalapból oldódik fel, így a középre vagy hátra igazított, kivágott tartalom a megfelelő látható részt választja ki A

Transform[M11 M12 M21 M22 MDX MDY]

SlotLeft jelenti a logikai elrendezési mátrixot (SlotTop), amely a komponens helyi koordinátáiból a végső, felülről lefelé értelmezett dokumentumkoordinátákba térképez A SlotWidth, SlotHeight,

Lapozási szabályok

`dppAllowSplit`	Megőrzi az alapértelmezett viselkedést, és minden érvényes töredéket véglegesít, amelynek visszahívása további tartalmat jelez
`dppKeepTogether`	`PDF_DYNAMIC_COMPONENT_RETRY` értéket ad vissza az első, részleges vagy nem látható kísérletre, majd a következő érvényes kísérletnél megengedi ugyanazon, nem véglegesített töredék osztását vagy a kiválasztott kivágási tartalékot
`dppRequireComplete`	`PDF_DYNAMIC_COMPONENT_RETRY` értéket ad vissza, amíg a visszahívás jelzi, hogy nincs fennmaradó tartalom, és a teljes felhasznált téglalap vagy belefér a helybe, vagy arányos lekicsinyítéssel látható marad

Placement

KeepTogetherRetryPending rekordot ad vissza A Reset azonosítja az egyszeri tartalék állapotot, és sikeres véglegesítés, AttachComponent vagy

Folyamtér-korlátozások

`MinimumSlotHeight`	`PDF_DYNAMIC_COMPONENT_RETRY` értéket ad vissza a komponens klónozása vagy meghívása előtt, amikor a célhely rövidebb, mint a konfigurált magasság
`MinimumFollowingHeight`	Csak záró tartalomtöredékre vonatkozik, és megköveteli, hogy a feloldott magassága a lefoglalt követő magassággal együtt beférjen a helybe

A követőmagasság-újrapróbálás eldobja az izolált kísérletet, miközben megtartja a korábban véglegesített töredékeket, így egy cím, felirat vagy rövid bevezető a következő komponens első használható területével együtt mozoghat A

LastRetryReason megkülönbözteti a teljes-komponens, szigorú-befejezés, minimális-lyuk és követő-terület újrapróbálásokat, míg LastRequiredSlotHeight az ismert szükséges magasságot jelenti a folyami térbeli korlátokhoz

A minimum-hely ellenőrzés a komponens klónozása és Form rögzítése előtt fut, így a ismételten elutasított rövid régiók nem viselnek komponens-visszahívási vagy ideiglenes oldalköltséget

Visszatérési értékek

`PDF_DYNAMIC_COMPONENT_ERROR`	A kérés, a komponensvisszahívás, az eredménygeometria vagy a Form elhelyezés meghiúsult, és egyetlen állapot sem került véglegesítésre
`PDF_DYNAMIC_COMPONENT_MORE`	A tartalom véglegesítésre került, és a komponens egy további oldalhelyet kért
`PDF_DYNAMIC_COMPONENT_COMPLETE`	A komponens befejeződött, vagy a munkamenet már korábban befejeződött, és visszahívás nem történt
`PDF_DYNAMIC_COMPONENT_RETRY`	A kiválasztott lapszámolási vagy folyamterületi szabályzat a tartalom vagy állapot véglegesítése nélkül halasztotta az elhelyezést

Példa

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;

Lásd még

BeginFormXObject, ReleaseCapturedPage, ApplyRepeatedPageFragment