Click or drag to resize

Get access, create and manipulate destinations

This topic contains the following sections:

Overview

Patagames PDF SDK provides APIs to access, create and manipulate destinations. A destination defines a particular view of a document, consisting of the following items:

  • The page of the document to be displayed

  • The location of the document window on that page

  • The magnification (zoom) factor to use when displaying the page

Destinations may be associated with bookmarks, annotations, or actions. In each case, the destination specifies the view of the document to be presented when the bookmark or annotation is opened or the action is performed. In addition, the optional OpenDestination may specify a destination to be displayed when the document is opened.

A destination may be specified either explicitly or indirectly by name. The 2nd capability is especially useful when the destination is located in another PDF document. For example, a link to the beginning of Chapter 2 in another document might refer to the destination by a name, such as Chap2.begin, instead of by an explicit page number in the other document. Then, the location of the chapter in the other document could change without invalidating the link. If an annotation or bookmark that refers to a named destination has an associated action, such as a remote go-to action or a thread action , the destination is in the file specified by the action’s FileSpecification property, if any; if FileSpecification is null, the destination is in the current file.

Destination Type

Description

Supported by SDK

XYZ

Display the page designated by page, with the coordinates (left, top) positioned at the upper-left corner of the window and the contents of the page magnified by the factor zoom.

Yes

Fit

Display the page designated by page, with its contents magnified just enough to fit the entire page within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the page within the window in the other dimension.

Yes

FitH

Display the page designated by page, with the vertical coordinate top positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of the page within the window.

Yes

FitV

Display the page designated by page, with the horizontal coordinate left positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of the page within the window.

Yes

FitR

Display the page designated by page, with its contents magnified just enough to fit the rectangle specified by the coordinates left, bottom, right, and top entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the rectangle within the window in the other dimension.

Yes

FitB

Display the page designated by page, with its contents magnified just enough to fit its bounding box entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the bounding box within the window in the other dimension.

Yes

FitBH

Display the page designated by page, with the vertical coordinate top positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of its bounding box within the window.

Yes

FitBV

Display the page designated by page, with the horizontal coordinate left positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of its bounding box within the window.

Yes

Open in full size

Destinations
Working with Explicit Destination

Creating explicit destinations

The following code example shows how to create XYZ destination.

This type of destination display the page designated by PageIndex, with the coordinates (Left, Top) positioned at the upper-left corner of the window and the contents of the page magnified by the factor Zoom.

C#
//Set the location
float left = 0;
float top = 400;
//Set zoom factor to 400 percentage
float zoom = 4;
var dest = PdfDestination.CreateXYZ(doc, pageIndex, left, top, zoom);

A null value for any of the parameters left, top, or zoom specifies that the current value of that parameter is to be retained unchanged. A zoom value of 0 has the same meaning as a null value.

C#
//The left, top and zoom parameters can be omitted.
var dest = PdfDestination.CreateXYZ(doc, pageIndex);

The destination can point to a position on a remote document. In this case, null is passed in the Document parameter.

C#
//The document parameter can be NULL.
//This means that the destination indicates a location in the remote document.
var dest = PdfDestination.CreateXYZ(null, pageIndex);

Destinations of all other types are created in a similar way, using the appropriate static method:

The destination can also be created using the constructor.

C#
var dest = new PdfDestination(doc);
//Set the type of destination
dest.DestinationType = DestinationTypes.XYZ;
//Set page index;
dest.PageIndex = 1;
//Set the location
dest.Left = 0;
dest.Top = 400;
//Set zoom factor to 400 percentage
dest.Zoom = 4;
Working with Named Destination

Patagames PDF SDK provides support to add, remove and modify the named destination in the PDF document.

How to enumerate the named destinations

C#
using (var doc = PdfDocument.Load("sample.pdf"))
{
    foreach(var dest in doc.NamedDestinations)
    {
        //The name of the destination to jump
        string destiationName = dest.Name;

        switch(dest.DestinationType)
        {
            case DestinationTypes.XYZ:
                var location = new FS_POINTF(dest.Left ?? 0, dest.Top ?? 0);
                float zoom = dest.Zoom ?? 1;
                break;
            case DestinationTypes.Fit:
            case DestinationTypes.FitB:
                //Fit destinations has no any parameters;
                break;
            case DestinationTypes.FitH:
            case DestinationTypes.FitBH:
                float top = dest.Top ?? 0;
                break;
            case DestinationTypes.FitV:
            case DestinationTypes.FitBV:
                float left = dest.Left ?? 0;
                break;
            case DestinationTypes.FitR:
                var rect = new FS_RECTF(dest.Left ?? 0, dest.Top ?? 0, dest.Right ?? 0, dest.Bottom ?? 0);
                break;
        }
    }
}

Adding Named Destination to a PDF document

You can add, remove and modify the named destination using PdfDestinationCollections class. An instance of this class can be obtained from the NamedDestinations property.

The following code example shows how to add named destination in an existing PDF document using the NamedDestinations.

C#
using (var doc = PdfDocument.Load("sample.pdf"))
{
    // Create destination that display the page designated by pageIndex 
    // in the document designated by doc, with its contents magnified just enough 
    // to fit the entire page within the window both horizontally and vertically.
    int pageIndex = 3;
    PdfDestination dest = PdfDestination.CreateFit(doc, pageIndex);

    //Add destination to NamedDestinations collection
    //dest.Name will become "MyDestinationName"
    doc.NamedDestinations.Add(dest, "MyDestinationName");

    //Save a copy of PDF document
    doc.Save("sample_with_named_destination.pdf", SaveFlags.NoIncremental);
}

Removing the named destination

You can remove the named destination using PdfDestinationCollectionsRemove method. The following code snippet illustrates the same.

C#
using (var doc = PdfDocument.Load("sample_with_named_destination.pdf"))
{
    //Remove the named destination by name
    if (doc.NamedDestinations.Remove("MyDestinationName"))
    {
        //the named destination was deleted successfully.
    }
    else
    {
        //There is no named destination with this name.
    }

    //Save a copy of PDF document
    doc.Save("sample_copy.pdf", SaveFlags.NoIncremental);
}

Modifying the named destination

C#
using (var doc = PdfDocument.Load("sample_with_named_destination.pdf"))
{
    //Get the named destination by name
    var dest = doc.NamedDestinations["MyDestinationName"];
    if (dest != null)
    {
        dest.DestinationType = DestinationTypes.XYZ;
        dest.Left = 10;
        dest.Top = 50;
        dest.Zoom = null;
    }

    //Save a copy of PDF document
    doc.Save("sample_copy.pdf", SaveFlags.NoIncremental);
}

Adding named destination to the bookmarks

C#
using (var doc = PdfDocument.Load("sample"))
{
    // Create explicit destination that display the page designated by pageIndex 
    // in the document designated by doc, with its contents magnified just enough 
    // to fit the entire page within the window both horizontally and vertically.
    int pageIndex = 3;
    PdfDestination dest = PdfDestination.CreateFit(doc, pageIndex);

    //Add explicit destination to NamedDestinations collection
    doc.NamedDestinations.Add(dest, "MyDestinationName");

    //Insert named destination into bookmark collection
    doc.Bookmarks.InsertAt(0, "My Bookmark", dest);

    //Save a copy of PDF document
    doc.Save("sample_with_named_destination.pdf", SaveFlags.NoIncremental);
}

Adding remote named destination to the bookmarks

C#
using (var doc = PdfDocument.Load("sample"))
{
    // Create a remote named destination
    PdfDestination dest = new PdfDestination(null, "Named_Destination_In_Embedded_Document");

    //Create a PDF attachment and embed it in the current document.
    var attachment = new PdfAttachment(doc, "other_document.pdf", System.IO.File.ReadAllBytes(@"c:\other_document.pdf"));
    doc.Attachments.Add(attachment);

    //Create a GoToE action
    var action = new PdfGoToEAction(doc, attachment.FileSpecification, dest);

    //Insert action into bookmark collection
    doc.Bookmarks.InsertAt(0, "My Bookmark", action);

    //Save a copy of PDF document
    doc.Save("sample_with_named_destination.pdf", SaveFlags.NoIncremental);
}
See Also