Get access, create and manipulate destinations

This topic contains the following sections:

Overview
Working with Explicit Destination

Creating explicit destinations

Working with Named Destination

How to enumerate the named destinations
Adding Named Destination to a PDF document
Removing the named destination
Modifying the named destination
Adding named destination to the bookmarks
Adding remote named destination to the bookmarks

See Also

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

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.

Copy

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

Copy

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

Copy

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

Copy

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

Copy

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.

Copy

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.

Copy

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

Copy

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

Copy

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

Copy

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);
}

Reference

Patagames.Pdf.NetPdfDestinationCollections

PdfDocumentNamedDestinations

PdfDestinationCollectionsRemove

Patagames.Pdf.NetPdfBookmarkCollections

PdfDocumentBookmarks

Patagames.Pdf.NetPdfDestination

PdfDestination.#ctor(PdfDocument, IntPtr, String)

Other Resources