TPDFlibDynamicComponentSession

تخطيط الصفحة، تقسيم الصفحات، أنواع البيانات

الوصف

يلّف مكونًا ذا حالة صفحة وجهة واحدة في كل مرة دون بناء محتوى مسبق للصفحات اللاحقة

تجري كل محاولة على نسخة داخل 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 بإحداثيات Form المحلية التي يكون مقاسها المتاح AvailableWidth في AvailableHeight
• يعين PageNumber صفحة الوجهة حتى لو اختارت المكتبة صفحة مؤقتة معزولة أثناء عمل دالة الاستدعاء
• يجوز لدالة الاستدعاء استخدام واجهات الرسم والمحتوى لكن عليها ألا تغيّر المستندات أو الصفحات أو حاويات الرسم المتداخلة
• تتطلب نتائج المحتوى قيم UsedWidth وUsedHeight منتهية موجبة ضمن لوحة المحتوى
• يبدأ المستطيل المستخدم من الإحداثي المحلي صفر وعليه أن يحوط كل محتوى المكوّن المرئي
• لا تكون نتيجة بلا محتوى صالحة إلا عندما تكون HasMoreContent بالقيمة False وكلا البعدين المستخدمين صفرًا
• يؤدي إرجاع الصفر إلى رفض المحاولة؛ وتنتشر الاستثناءات المرفوعة بعد تنظيف الحالة المؤقتة

الطرق

التجاوز والتموضع

تُحسم المحاذاة من المستطيل المستخدم المحوَّل، فيختار المحتوى المقصوص الموسّط أو اللاحق الجزء المرئي المقابل يبلّغ

Transform[M11 M12 M21 M22 MDX MDY]

SlotLeft عن مصفوفة التخطيط المنطقية SlotTop من إحداثيات المكوّن المحلية إلى إحداثيات المستند النهائية من الأعلى إلى الأسفل تحفظ SlotWidth وSlotHeight و

سياسات تقسيم الصفحات

Placement

KeepTogetherRetryPending فارغًا يعين Reset حالة الرجوع لمرة واحدة ويُمسح بعد إيداع ناجح أو AttachComponent أو

قيود مساحة التدفق

يتجاهل إعادة المحاولة لارتفاع تالٍ التجربة المعزولة مع حفظ الأجزاء المودَعة سابقًا، مما يسمح لعنوان أو تسمية أو مقدمة قصيرة بالانتقال مع أول منطقة قابلة للاستخدام من المكوّن التالي يميز

يميز LastRetryReason بين إعادة المحاولة للمكون الكامل والإكمال الصارم والخانة الدنيا والمساحة التالية، بينما يبلغ LastRequiredSlotHeight عن الارتفاع المطلوب المعروف لقيود تدفق المساحة

يجري فحص الخانة الدنيا قبل استنساخ المكون والتقاط Form فلا تكلّف المناطق القصيرة المرفوضة مرارًا استدعاء مكون أو صفحة مؤقتة

قيم الإرجاع

مثال

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