TPDFlibDynamicComponentSession

Pagina-indeling, paginering, gegevenstypen

Beschrijving

Componeert een stateful component één doelpagina tegelijk zonder vooraf inhoud voor latere pagina's op te bouwen

Elke poging draait op een kloon binnen een geïsoleerd Form XObject en legt de kloon pas vast nadat gevalideerde inhoud met succes is geplaatst

Uitgebreide plaatsing kan overflow afwijzen, inhoud op natuurlijke grootte afknippen of haar evenredig verkleinen terwijl ze binnen een doelslot wordt uitgelijnd

Pagineringsbeleid kan normale splitsing toestaan, het eerste partieele fragment uitstellen naar een verse regio of vereisen dat de hele component zichtbaar blijft voordat iets wordt vastgelegd

Flow-space-beperkingen kunnen een korte regio afwijzen voordat de component wordt aangeroepen of na het laatste fragment genoeg hoogte reserveren voor een volgende component

Een geweigerd resultaat, een mislukte tekenaanroep of een callback-exception verwijdert de tijdelijke pagina, herstelt de door de caller geselecteerde pagina en laat doelinhoud en huidige componenttoestand ongewijzigd

TPDFlib-instantie blijft eigendom van de aanroeper en moet de sessie overleven

Declaratie

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;

Componentcontract

CloneComponent geeft een van de aanroeper onafhankelijke kopie van alle veranderlijke pagineringsstatus terug
Compose tekent via Context.LibraryInstance in lokale Form-coördinaten waarvan de beschikbare grootte AvailableWidth bij AvailableHeight is
PageNumber identificeert de doelpagina, ook al kiest de bibliotheek een geïsoleerde tijdelijke pagina terwijl de callback draait
De callback mag teken- en content-API's gebruiken maar mag documenten, pagina's of geneste tekencontainers niet wijzigen
Inhoudsresultaten vereisen eindige positieve UsedWidth- en UsedHeight-waarden binnen het inhoudscanvas
De gebruikte rechthoek begint op lokale coördinaat nul en moet alle zichtbare componentinhoud omsluiten
Een resultaat zonder inhoud is alleen geldig wanneer HasMoreContent False is en beide gebruikte dimensies nul zijn
Het teruggeven van nul wijst de poging af; veroorzaakte exceptions propageren nadat de tijdelijke status is opgeruimd

Methoden

Create	Koppelt een bibliotheek in eigendom van de aanroeper en kloont de aangeleverde component naar onafhankelijke initiële en huidige momentopnamen
AttachComponent	Vervangt atomair beide momentopnamen door klonen van een component in eigendom van de aanroeper en wist de voltooiingsstatus
Reset	Herstelt een nieuwe huidige kloon vanuit de initiële momentopname en reset het aantal geslaagde samenstellingen
CloneCurrentComponent	Geeft een kloon in eigendom van de aanroeper terug om de huidige vastgelegde componentstatus te inspecteren
CreateLayoutOptions	Bouwt getypeerde instellingen voor natuurlijk canvas, overloop, uitlijning, paginering en stroomruimte voor uitgebreide plaatsing
ComposeNext	Stelt één paginavak samen, valideert en plaatst zijn Form XObject, geeft de vastleggingshandle vrij en legt de werkstatus vast
ComposeNextLayout	Stelt samen op het geconfigureerde natuurlijke canvas, past overloop- en uitlijningsbeleid toe en geeft bron-, vak- en eindtransformatiegegevens terug

Overloop en plaatsing

`dopReject`	Wijst inhoud af die breder of hoger is dan het vak zonder bestemmingsinhoud of vastgelegde componentstatus te wijzigen
`dopClip`	Houdt schaal 1 aan en snijdt het pagina-knippad bij met het bestemmingsvak vóór het aanroepen van het Form XObject
`dopScaleDown`	Gebruikt de kleinste breedte- of hoogteverhouding alleen wanneer nodig en vergroot inhoud nooit

Uitlijning wordt bepaald vanuit de getransformeerde gebruikte rechthoek, zodat gecentreerde of achterliggende bijgesneden inhoud het bijbehorende zichtbare deel kiest

Transform meldt de logische layoutmatrix [M11 M12 M21 M22 MDX MDY] van componentlokale coördinaten naar de uiteindelijke documentcoördinaten van boven naar beneden

SlotLeft rapporteert de logische lay-outmatrix SlotTop van component-lokale coördinaten naar de definitieve top-down documentcoördinaten SlotWidth, SlotHeight,

Pagineringsbeleid

`dppAllowSplit`	Behoudt het standaardgedrag en legt elk geldig fragment vast waarvan de callback meer inhoud rapporteert
`dppKeepTogether`	Geeft `PDF_DYNAMIC_COMPONENT_RETRY` terug voor de eerste gedeeltelijke of niet-zichtbare proef, en staat daarna splitsen of de gekozen bijsnijfallback toe bij de volgende geldige poging voor hetzelfde niet-vastgelegde fragment
`dppRequireComplete`	Geeft `PDF_DYNAMIC_COMPONENT_RETRY` terug totdat de callback geen resterende inhoud meer rapporteert en de volledige gebruikte rechthoek in het vak past of na proportioneel verkleinen volledig zichtbaar blijft

Een herhaling werpt de Form XObject-proef weg, behoudt doelpagina, componentsnapshot, voltooiingsvlag en compositieaantal en geeft een leeg Placement-record terug

KeepTogetherRetryPending-record terug Reset identificeert de eenmalige fallbackstatus en wordt gewist na een geslaagde vastlegging, AttachComponent of

Stroomruimtebeperkingen

`MinimumSlotHeight`	Geeft `PDF_DYNAMIC_COMPONENT_RETRY` terug vóór het klonen of aanroepen van het component wanneer het bestemmingsvak korter is dan de geconfigureerde hoogte
`MinimumFollowingHeight`	Geldt alleen voor een definitief inhoudsfragment en vereist dat zijn opgeloste hoogte plus de gereserveerde volghoogte in het vak past

Een volghoogte-herpoging gooit de geïsoleerde proef weg terwijl eerder vastgelegde fragmenten behouden blijven, zodat een kop, label of korte inleiding kan meebewegen naar de eerste bruikbare regio van het volgende component

LastRetryReason onderscheidt herhalingen voor hele component, strikte voltooiing, minimumslot en volgende ruimte, terwijl LastRequiredSlotHeight de bekende vereiste hoogte voor flow-space-beperkingen meldt

De minimumslotcontrole draait vóór het klonen van de component en het vastleggen van de Form, dus herhaaldelijk geweigerde korte regio's kosten geen componentcallback of tijdelijke pagina

Retourwaarden

`PDF_DYNAMIC_COMPONENT_ERROR`	Het verzoek, de componentcallback, de resultaatgeometrie of de Form-plaatsing is mislukt en er is geen status vastgelegd
`PDF_DYNAMIC_COMPONENT_MORE`	Inhoud is vastgelegd en het component vroeg een nieuw paginavak aan
`PDF_DYNAMIC_COMPONENT_COMPLETE`	Het component is voltooid, of de sessie was al voltooid en er is geen callback gedaan
`PDF_DYNAMIC_COMPONENT_RETRY`	Het gekozen paginerings- of stroomruimtebeleid heeft de plaatsing uitgesteld zonder inhoud of status vast te leggen

Voorbeeld

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;

Zie ook

BeginFormXObject, ReleaseCapturedPage, ApplyRepeatedPageFragment