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

The Form XObject canvas follows ContentWidth and ContentHeight, while alignment uses the component-reported used rectangle anchored at local coordinate zero

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