TPDFlibDynamicComponentSession

چیدمان صفحه، صفحه‌بندی، انواع داده

توضیحات

یک مؤلفه حالت‌مند را هر بار روی یک صفحه مقصد ترکیب می‌کند بدون آنکه محتوای صفحه‌های بعدی را از پیش بسازد هر تلاش روی یک کلون درون یک Form XObject مجزا اجرا می‌شود و کلون تنها پس از جای‌گذاری موفق محتوای اعتبارسنجی‌شده ثبت می‌گردد جای‌گذاری گسترش‌یافته می‌تواند سرریز را رد کند، محتوای با اندازه طبیعی را برش دهد یا آن را متناسب کوچک کند، هم‌زمان با ترازکردنش در جایگاه مقصد سیاست صفحه‌بندی می‌تواند شکافتن عادی را مجاز کند، نخستین قطعه ناقص را به ناحیه‌ای تازه مؤخر کند یا الزام کند کل مؤلفه پیش از ثبت هر چیزی مرئی بماند قیدهای فضای جریان می‌توانند ناحیه کوتاه را پیش از فراخوانی مؤلفه رد کنند یا پس از آخرین قطعه‌اش ارتفاع کافی برای مؤلفه بعدی رزرو کنند نتیجه ردشده، فراخوانی رسم ناموفق یا استثنای callback، صفحه موقت را حذف، صفحه برگزیده فراخوان را بازمی‌گرداند و محتوای مقصد و حالت جاری مؤلفه را بدون تغییر می‌گذارد نمونه

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 در مختصات محلی Form رسم می‌کند که اندازه در دسترسش AvailableWidth در AvailableHeight است
• PageNumber صفحه مقصد را شناسایی می‌کند حتی اگر کتابخانه هنگام اجرای callback یک صفحه موقت مجزا انتخاب کند
• callback می‌تواند از APIهای رسم و محتوا استفاده کند اما نباید اسناد، صفحه‌ها یا ظرف‌های رسم تودرتو را تغییر دهد
• نتایج محتوا به مقادیر UsedWidth و UsedHeight متناهی و مثبت درون بوم محتوا نیاز دارند
• مستطیل استفاده‌شده از مختصات محلی صفر آغاز می‌شود و باید همه محتوای مرئی مؤلفه را دربر گیرد
• نتیجه بدون محتوا تنها وقتی معتبر است که HasMoreContent برابر False و هر دو بُعد استفاده‌شده صفر باشد
• برگرداندن صفر تلاش را رد می‌کند؛ استثناهای پرتاب‌شده پس از پاک‌سازی حالت موقت منتشر می‌شوند

متدها

سرریز و جای‌گذاری

تراز از مستطیل استفاده‌شده تبدیل‌شده حل می‌شود، بنابراین محتوای برش‌خورده وسط‌چین یا انتهایی، بخش مرئی متناظر را برمی‌گزیند

Transform[M11 M12 M21 M22 MDX MDY]

SlotLeft ماتریس چیدمان منطقی SlotTop را از مختصات محلی مؤلفه به مختصات نهایی بالا‌به‌پایین سند گزارش می‌کند SlotWidth، SlotHeight،

سیاست‌های صفحه‌بندی

Placement

KeepTogetherRetryPending را برمی‌گرداند Reset حالت fallback یک‌باره را شناسایی می‌کند و پس از یک ثبت موفق، AttachComponent یا

محدودیت‌های فضای جریان

یک تلاش مجدد ارتفاع بعدی، آزمایش مجزا را دور می‌ریزد در حالی که قطعه‌های ثبت‌شده پیشین را حفظ می‌کند و امکان می‌دهد یک عنوان، برچسب یا مقدمه کوتاه با نخستین ناحیه قابل‌استفاده مؤلفه بعدی حرکت کند

LastRetryReason تلاش‌های مجدد کل‌مؤلفه، تکمیل سخت‌گیرانه، حداقل‌جایگاه و فضای بعدی را متمایز می‌کند، در حالی که LastRequiredSlotHeight ارتفاع لازم شناخته‌شده برای قیدهای فضای جریان را گزارش می‌کند بررسی حداقل‌جایگاه پیش از کلون‌گیری مؤلفه و گرفتن Form اجرا می‌شود، بنابراین نواحی کوتاه مکرراً ردشده هیچ هزینه callback مؤلفه یا صفحه موقتی ندارند

مقادیر بازگشتی

مثال

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