![]() | Get access, create and manipulate destinations |
This topic contains the following sections:
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 |
---|---|---|
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 |
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.
//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.
//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.
//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.
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;
Patagames PDF SDK provides support to add, remove and modify the named destination in the PDF document.
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; } } }
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.
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); }
You can remove the named destination using PdfDestinationCollectionsRemove method. The following code snippet illustrates the same.
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); }
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); }
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); }
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); }