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 ในพิกัดฟอร์มท้องถิ่นที่ขนาดพร้อมใช้คือ AvailableWidth คูณ AvailableHeight
• PageNumber ระบุหน้าปลายทาง แม้ไลบรารีจะเลือกหน้าชั่วคราวแบบแยกส่วนขณะคอลแบ็กทำงาน
• คอลแบ็กใช้ API การวาดและเนื้อหาได้ แต่ห้ามเปลี่ยนเอกสาร หน้า หรือคอนเทนเนอร์การวาดที่ซ้อนกัน
• ผลลัพธ์เนื้อหาต้องการ UsedWidth และ UsedHeight ที่มีค่าจำกัดและเป็นบวก ภายในผืนผ้าใบเนื้อหา
• สี่เหลี่ยมที่ใช้เริ่มที่พิกัดท้องถิ่นศูนย์ และต้องครอบคลุมเนื้อหาของคอมโพเนนต์ที่มองเห็นได้ทั้งหมด
• ผลลัพธ์แบบไม่มีเนื้อหาถูกต้องก็ต่อเมื่อ HasMoreContent เป็น False และทั้งสองมิติที่ใช้เป็นศูนย์
• การคืนค่าศูนย์จะปฏิเสธความพยายาม, ข้อยกเว้นที่ยกขึ้นจะแพร่กระจายหลังสถานะชั่วคราวถูกทำความสะอาดแล้ว

เมธอด

การล้นและการวางตำแหน่ง

การจัดแนวถูกแก้ไขจากสี่เหลี่ยมที่ใช้หลังแปลง เนื้อหาที่ถูกตัดแบบอยู่กึ่งกลางหรือท้ายจึงเลือกส่วนที่มองเห็นได้ที่สอดคล้องกัน

Transform[M11 M12 M21 M22 MDX MDY]

SlotLeft รายงานเมทริกซ์ผังเชิงตรรกะ SlotTop จากพิกัดของคอมโพเนนต์ไปยังพิกัดเอกสารบนลงล่างสุดท้าย SlotWidth, SlotHeight,

นโยบายการแบ่งหน้า

Placement

KeepTogetherRetryPending ที่ว่างเปล่า 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