Destination - TPdf

يحافظ إدخال API هذا على المعرّفات والتواقيع وكتل الكود ومصطلحات PDF بصيغتها الأصلية.

Component: TPdf · Unit: PDFium

Returns the TDestination record for the named destination at the specified zero-based index. Named destinations are the indirect targets defined under the document catalog Dests / Names tree as described in PDF section 12.3.2.

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.

PDFiumVCL 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, target page number (1-based), view coordinates (X, Y), zoom factor, and Boolean flags indicating whether each component was explicitly set by the author.

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.
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