ComposeNextLayout

Page layout, pagination, Form XObjects

Description

Composes one stateful dynamic fragment on a natural-size canvas, applies overflow, alignment, pagination and flow-space policy and reports the final placement transform

Syntax

Function TPDFlibDynamicComponentSession.ComposeNextLayout(
  Page: Integer; SlotLeft, SlotTop, SlotWidth, SlotHeight: Double;
  Const Options: TPDFlibDynamicLayoutOptions;
  Out Placement: TPDFlibDynamicPagePlacement): Integer;

Parameters

`Page`	Existing one-based destination page number
`SlotLeft`, `SlotTop`	Top-left destination slot position in current document units
`SlotWidth`, `SlotHeight`	Finite positive destination slot size
`Options.ContentWidth`, `Options.ContentHeight`	Finite positive natural canvas passed to the component through `AvailableWidth` and `AvailableHeight`
`Options.OverflowPolicy`	`dopReject`, `dopClip` or `dopScaleDown`
`Options.HorizontalAlignment`	`dhaLeft`, `dhaCenter` or `dhaRight`
`Options.VerticalAlignment`	`dvaTop`, `dvaCenter` or `dvaBottom`
`Options.PaginationPolicy`	Normal splitting, one-shot keep-together fallback or strict complete placement
`Options.MinimumSlotHeight`	Non-negative slot height required before component cloning and composition start
`Options.MinimumFollowingHeight`	Non-negative height reserved after a final resolved fragment for the next component

Placement result

`PageNumber`, `CompositionIndex`	Committed page and one-based successful composition number
`SourceWidth`, `SourceHeight`	Natural used rectangle returned by the component before placement
`Left`, `Top`, `Width`, `Height`	Final transformed used rectangle before destination clipping
`SlotLeft`, `SlotTop`, `SlotWidth`, `SlotHeight`	Original destination region
`Transform`	Logical affine matrix from component-local coordinates to final top-down document coordinates
`WasClipped`	True when clipping hides part of the transformed used rectangle
`WasScaled`	True when proportional scale is less than 1

Remarks

dopReject preserves the destination page and committed component state when the natural used rectangle exceeds either slot dimension

dopClip preserves natural scale and uses a balanced graphics-state clipping scope around the Form XObject invocation

dopScaleDown chooses Min(1, SlotWidth / SourceWidth, SlotHeight / SourceHeight) and preserves the component aspect ratio

Scaling never enlarges content that already fits

ContentWidth and preserves the component aspect ratio Scaling never enlarges content that already fits The Form XObject canvas follows ContentHeight and

The page content stream owns the placed Form XObject reference before the temporary capture handle is released

A slot shorter than MinimumSlotHeight returns retry without cloning the component, invoking its callback or creating a temporary page

MinimumFollowingHeight does not constrain intermediate fragments and is checked only when HasMoreContent is false

A flow-space retry returns an empty placement, preserves all previously committed fragments and exposes its reason and required height through LastRetryReason and LastRequiredSlotHeight

Example

Options := TPDFlibDynamicComponentSession.CreateLayoutOptions(
  640, 360, dopScaleDown, dhaLeft, dvaTop, dppAllowSplit, 72, 24);

Status := Session.ComposeNextLayout(
  PageNumber, 36, 72, 540, 240, Options, Placement);

if Status <> PDF_DYNAMIC_COMPONENT_ERROR then
begin
  FinalScale := Placement.Transform.M11;
  FinalLeft := Placement.Left;
  FinalTop := Placement.Top;
end;

Return values

`PDF_DYNAMIC_COMPONENT_ERROR`	Input, callback, geometry, overflow or placement validation failed without committing state
`PDF_DYNAMIC_COMPONENT_MORE`	The fragment was committed and more content remains
`PDF_DYNAMIC_COMPONENT_COMPLETE`	The fragment completed the session or the session was already complete
`PDF_DYNAMIC_COMPONENT_RETRY`	Pagination or flow-space policy deferred the uncommitted trial to another slot