Destination - TPdf - PDFium Delphi Component

Component: TPdf · Unit: PDFium

Returns a named destination with its target page, PDF view mode, raw view parameters, coordinates, and zoom flags

Syntax

property Destination[Index: Integer]: TDestination; // read only

Description

A named destination is a symbolic name (for example "chap5.fig3") stored in the PDF document catalog that resolves to a concrete page-position-zoom tuple. They let outlines, link annotations, and external documents reference a target by stable name rather than by hard-coded page coordinates, so the document can be re-paginated without breaking inbound links

PDFium Delphi Component flattens both legacy /Dests dictionaries and modern /Names /Dests name trees into a single zero-based list. Destination[Index] returns a TDestination record carrying the destination name, one-based target page, decoded ViewMode, raw ViewParameters, view coordinates, zoom factor, and presence flags

Use DestinationCount to obtain the total number of named destinations, iterate with Destination[I], and use DestinationByName when you already know the target name

Parameters

Index Integer. Zero-based position in the flattened named-destinations list. Must be in [0, DestinationCount - 1]. An out-of-range index returns a zero-filled record with Handle = nil.

Remarks

HasX, HasY, and HasZoom distinguish "fit page" / "fit width" destinations (where these components are absent) from explicit XYZ destinations. Apply only the components that are marked present
ViewMode distinguishes XYZ, Fit, FitH, FitV, FitR, FitB, FitBH, and FitBV destinations without requiring callers to decode PDFium constants
ViewParameterCount gives the number of valid entries in the fixed four-element ViewParameters array
PDFium reports view coordinates in PDF user space (origin bottom-left, points). Convert with the page MediaBox if you need device-space pixels
An external document may reference a name that does not exist in this PDF — that lookup returns an empty record. Always test Handle before navigating

Example

var
  I: Integer;
  Dest: TDestination;
begin
  Pdf1.LoadFromFile('manual.pdf');
  Memo1.Lines.Add(Format('%d named destinations:', [Pdf1.DestinationCount]));
  for I := 0 to Pdf1.DestinationCount - 1 do
  begin
    Dest := Pdf1.Destination[I];
    Memo1.Lines.Add(Format('%s -> page %d (X=%.1f Y=%.1f Zoom=%.2f)',
      [Dest.Name, Dest.PageNumber, Dest.X, Dest.Y, Dest.Zoom]));
  end;
  // Navigate to the first destination
  if Pdf1.DestinationCount > 0 then
    Pdf1.PageNumber := Pdf1.Destination[0].PageNumber;
end;

Destination property