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 רשאי להשתמש ב-APIs של ציור ותוכן אך לא ישנה מסמכים, עמודים או מכלי ציור מקוננים
• תוצאות תוכן דורשות ערכי UsedWidth ו-UsedHeight סופיים וחיוביים בתוך בד התוכן
• המלבן בשימוש מתחיל בקואורדינטה מקומית אפס ויחסום את כל תוכן הרכיב הגלוי
• תוצאה ללא תוכן תקפה רק כאשר HasMoreContent הוא False ושני ממדי השימוש הם אפס
• החזרת אפס דוחה את הניסיון; חריגות שהועלו מתפשטות לאחר שהמצב הזמני נוקה

שיטות

גלישה והצבה

היישור נפתר מהמלבן בשימוש המותמר, כך שתוכן ממורכז או חתוך-סופי בוחר את החלק הגלוי המתאים

Transform[M11 M12 M21 M22 MDX MDY]

SlotLeft מדווח על מטריצת הפריסה הלוגית SlotTop מקואורדינטות מקומיות של הרכיב אל קואורדינטות המסמך הסופיות מלמעלה למטה SlotWidth, SlotHeight,

מדיניות עימוד

Placement

KeepTogetherRetryPending ריקה Reset מזהה את מצב החלופה החד-פעמי ומתנקה לאחר אישור מוצלח, 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