TPDFlibDynamicComponentSession

ページレイアウト、ページ分割、データ型

説明

ステートフルなコンポーネントを、後のページのコンテンツを先に作ることなく、一度に1つの宛先ページへ合成します

各試行は分離されたForm XObject内のクローン上で実行され、検証済みコンテンツの配置が成功した後にのみクローンをコミットします

拡張配置は、オーバーフローを拒否するか、自然サイズのコンテンツをクリップするか、宛先スロット内に整列させながら比例縮小できます

ページネーションポリシーは、通常の分割を許すこと、最初の部分フラグメントを新しい領域へ先送りすること、何かをコミットする前にコンポーネント全体を可視のまま要求することができます

フロースペースの制約は、コンポーネントを呼び出す前に短い領域を拒否することも、最終フラグメントの後ろに次のコンポーネントのための十分な高さを確保することもできます

拒否された結果、失敗した描画呼び出し、コールバック例外は一時ページを取り除き、呼び出し元が選択したページを復元し、宛先コンテンツと現在のコンポーネント状態の両方を変更しません

アタッチされたTPDFlibインスタンスは呼び出し元所有のまま残り、セッションより長く生存する必要があります

宣言

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;

コンポーネント契約

• CloneComponent はすべての可変改ページ状態の、呼び出し側から独立したコピーを返します
• Compose は、利用可能なサイズが Context.LibraryInstance × AvailableWidth であるローカル Form 座標で AvailableHeight を通じて描画します
• コールバックの実行中はライブラリが分離された一時ページを選択しますが、PageNumber は移動先ページを特定します
• コールバックは描画 API とコンテンツ API を使用できますが、ドキュメント、ページ、ネストされた描画コンテナを変更してはなりません
• コンテンツの結果には、コンテンツキャンバス内の有限の正の UsedWidth と UsedHeight が必要です
• 使用された矩形はローカル座標 0 から始まり、すべての可視コンポーネントコンテンツを包まなければなりません
• コンテンツなしの結果は、HasMoreContent が False で両方の使用寸法が 0 の場合にのみ有効です
• 0 を返すと試行が拒否されます。送出された例外は一時状態の後始末の後に伝播します

メソッド

オーバーフローと配置

配置は変換された使用矩形から解決されるため、中央揃えや末尾クリップされたコンテンツは対応する可視部分を選択します

Transformは、コンポーネントローカル座標から最終的な上から下のドキュメント座標への論理レイアウト行列[M11 M12 M21 M22 MDX MDY]を報告します

SlotLeft、SlotTop、SlotWidth、SlotHeightは、クリッピングの下で最終コンテンツ原点が外にあってでも、呼び出し元が指定した領域を保持します

ページネーションポリシー

リトライはForm XObjectの試行を破棄し、宛先ページ、コンポーネントスナップショット、完了フラグ、合成カウントを保持し、空のPlacementレコードを返します

KeepTogetherRetryPendingは1回限りのフォールバック状態を識別し、成功したコミット、Reset、AttachComponentの後にクリアされます

フロースペースの制約

後続高さのリトライは、以前にコミットされたフラグメントを保持したまま分離された試行を破棄するため、見出し、ラベル、短いリードインが次のコンポーネントの最初の使用可能領域と共に移動できます

LastRetryReasonはコンポーネント全体、厳密完了、最小スロット、後続スペースの各リトライを区別し、LastRequiredSlotHeightはフロースペース制約に対する既知の必要高さを報告します

最小スロットのチェックはコンポーネントのクローン作成とフォームキャプチャの前に実行されるため、繰り返し拒否される短い領域がコンポーネントコールバックや一時ページのコストを生みません

戻り値

例

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;

関連項目

BeginFormXObject, ReleaseCapturedPage, ApplyRepeatedPageFragment