Working with Actions in PDF using Aspose.PDF for .NET

It is possible to add hyperlinks to PDF files, either to allow readers to navigate to another part of the PDF, or to external content.

In order to add web hyperlinks to PDF documents:

  1. Create a Document Class object.
  2. Get the Page Class you want to add the link to.
  3. Create a LinkAnnotation object using the Page and Rectangle objects. The rectangle object is used to specify the location on the page where the link should be added.
  4. Set the Action property to the GoToURIAction object which specifies the location of the remote URI.
  5. To display a hyperlink text, add a text string on a location similar to where the LinkAnnotation object is placed.
  6. To add a free text:
  • Instantiate an FreeTextAnnotation object. It also accepts Page and Rectangle objects as argument, so it is possible to provide same values as specified against the LinkAnnotation constructor.
  • Using the FreeTextAnnotation object’s Contents property, specify the string that should be displayed in the output PDF.
  • Optionally, set the border width of both the LinkAnnotation and FreeTextAnnotation objects to 0 so that they do not appear in the PDF document.
  • Once the LinkAnnotation and FreeTextAnnotation objects have been defined, add these links to the Page object’s Annotations collection.
  • Finally, save the updated PDF using the Document object’s Save method.

The following code snippet shows you how to add a hyperlink to a PDF file.

// For complete examples and data files, please go to https://github.com/aspose-pdf/Aspose.PDF-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_AsposePdf_LinksActions();

// Open document
Document document = new Document(dataDir + "AddHyperlink.pdf");
// Create link
Page page = document.Pages[1];
// Create Link annotation object
LinkAnnotation link = new LinkAnnotation(page, new Aspose.Pdf.Rectangle(100, 100, 300, 300));
// Create border object for LinkAnnotation
Border border = new Border(link);
// Set the border width value as 0
border.Width = 0;
// Set the border for LinkAnnotation
link.Border = border;
// Specify the link type as remote URI
link.Action = new GoToURIAction("www.aspose.com");
// Add link annotation to annotations collection of first page of PDF file
page.Annotations.Add(link);

// Create Free Text annotation
FreeTextAnnotation textAnnotation = new FreeTextAnnotation(document.Pages[1], new Aspose.Pdf.Rectangle(100, 100, 300, 300), new DefaultAppearance(Aspose.Pdf.Text.FontRepository.FindFont("TimesNewRoman"), 10, System.Drawing.Color.Blue));
// String to be added as Free text
textAnnotation.Contents = "Link to Aspose website";
// Set the border for Free Text Annotation
textAnnotation.Border = border;
// Add FreeText annotation to annotations collection of first page of Document
document.Pages[1].Annotations.Add(textAnnotation);
dataDir = dataDir + "AddHyperlink_out.pdf";
// Save updated document
document.Save(dataDir);

Aspose.PDF for .NET provides a great feature to PDF creation as well as its manipulation. It also offers the feature to add links to PDF pages and a link can either direct to pages in another PDF file, a web URL, link to launch an Application or even link to pages in same PDF file. In order to add local hyperlinks (links to pages in same PDF file), a class named LocalHyperlink is added to Aspose.PDF namespace and this class has a property named TargetPageNumber, which is used to specify the target/destination page for hyperlink.

In order to add the local hyperlink, we need to create a TextFragment so that link can be associated with the TextFragment. The TextFragment class has a property named Hyperlink which is used to associate LocalHyperlink instance. The following code snippet shows the steps to accomplish this requirement.

// For complete examples and data files, please go to https://github.com/aspose-pdf/Aspose.PDF-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_AsposePdf_LinksActions();

// Create Document instance
Document doc = new Document();
// Add page to pages collection of PDF file
Page page = doc.Pages.Add();
// Create Text Fragment instance
Aspose.Pdf.Text.TextFragment text = new Aspose.Pdf.Text.TextFragment("link page number test to page 7");
// Create local hyperlink instance
Aspose.Pdf.LocalHyperlink link = new Aspose.Pdf.LocalHyperlink();
// Set target page for link instance
link.TargetPageNumber = 7;
// Set TextFragment hyperlink
text.Hyperlink = link;
// Add text to paragraphs collection of Page
page.Paragraphs.Add(text);
// Create new TextFragment instance
text = new TextFragment("link page number test to page 1");
// TextFragment should be added over new page
text.IsInNewPage = true;
// Create another local hyperlink instance
link = new LocalHyperlink();
// Set Target page for second hyperlink
link.TargetPageNumber = 1;
// Set link for second TextFragment
text.Hyperlink = link;
// Add text to paragraphs collection of page object
page.Paragraphs.Add(text);

dataDir = dataDir + "CreateLocalHyperlink_out.pdf";
// Save updated document
doc.Save(dataDir);

Links are represented as annotations in a PDF file and they can be added, updated or deleted. Aspose.PDF for .NET also supports getting the destination (URL) of the hyperlink in PDF file.

To get a link’s URL:

  1. Create a Document object.
  2. Get the Page you want to extract links from.
  3. Use the AnnotationSelector class to extract all the LinkAnnotation objects from the specified page.
  4. Pass the AnnotationSelector object to the Page object’s Accept method.
  5. Get all the selected link annotations into an IList object using the AnnotationSelector object’s Selected property.
  6. Finally, extract the LinkAnnotation Action as GoToURIAction.

The following code snippet shows how to get hyperlink destinations (URL) from a PDF file.

// For complete examples and data files, please go to https://github.com/aspose-pdf/Aspose.PDF-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_AsposePdf_LinksActions();
// Load the PDF file
Document document = new Document(dataDir + "input.pdf");

// Traverse through all the page of PDF
foreach (Aspose.Pdf.Page page in document.Pages)
{
    // Get the link annotations from particular page
    AnnotationSelector selector = new AnnotationSelector(new Aspose.Pdf.Annotations.LinkAnnotation(page, Aspose.Pdf.Rectangle.Trivial));

    page.Accept(selector);
    // Create list holding all the links
    IList<Annotation> list = selector.Selected;
    // Iterate through invidiaul item inside list
    foreach (LinkAnnotation a in list)
    {
        // Print the destination URL
        Console.WriteLine("\nDestination: " + (a.Action as Aspose.Pdf.Annotations.GoToURIAction).URI + "\n");
    }
}

A hyperlink has two parts: the text that shows in the document, and the destination URL. In some cases, it’s the text rather than the URL we need.

Text and annotations/actions in a PDF file are represented by different entities. Text on a page is just a set of words and characters, while annotations bring some interactivity such as that inherent in a hyperlink.

To find the URL content, you need to work with both annotation and text. The Annotation object does not have itself have the text but sits under the text on the page. So to get the text, the Annotation gives the URL’s bounds, while the Text object gives the URL contents. Please see the following code snippet.

  {
        public static void Run()
        {
            try
            {
                // ExStart:GetHyperlinkText
                // The path to the documents directory.
                string dataDir = RunExamples.GetDataDir_AsposePdf_LinksActions();
                // Load the PDF file
                Document document = new Document(dataDir + "input.pdf");
                // Iterate through each page of PDF
                foreach (Page page in document.Pages)
                {
                    // Show link annotation
                    ShowLinkAnnotations(page);
                }
                // ExEnd:GetHyperlinkText
            }
            catch (Exception ex)
            {
                Console.WriteLine(ex.Message);
            }
        }
        // ExStart:ShowLinkAnnotations
        public static void ShowLinkAnnotations(Page page)
        {
            foreach (Aspose.Pdf.Annotations.Annotation annot in page.Annotations)
            {
                if (annot is LinkAnnotation)
                {
                    // Print the URL of each Link Annotation
                    Console.WriteLine("URI: " + ((annot as LinkAnnotation).Action as GoToURIAction).URI);
                    TextAbsorber absorber = new TextAbsorber();
                    absorber.TextSearchOptions.LimitToPageBounds = true;
                    absorber.TextSearchOptions.Rectangle = annot.Rect;
                    page.Accept(absorber);
                    string extractedText = absorber.Text;
                    // Print the text associated with hyperlink
                    Console.WriteLine(extractedText);
                }

            }
        }
        // ExEnd:ShowLinkAnnotations
    }
}

Remove Document Open Action from a PDF File

How to Specify PDF Page when Viewing Document explained how to tell a document to open on a different page than the first. When concatenating several documents, and one or more has a GoTo action set, you probably want to remove them. For example, if combining two documents and the second one has a GoTo action that takes you to the second page, the output document will open on the second page of the second document instead of the first page of the combined document. To avoid this behavior, remove the open action command.

To remove an open action:

  1. Set the Document object’s OpenAction property to null.
  2. Save the updated PDF using the Document object’s Save method.

The following code snippet shows how to remove a document open action from the PDF file.

// For complete examples and data files, please go to https://github.com/aspose-pdf/Aspose.PDF-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_AsposePdf_LinksActions();
// Open document
Document document = new Document(dataDir + "RemoveOpenAction.pdf");
// Remove document open action
document.OpenAction = null;
dataDir = dataDir + "RemoveOpenAction_out.pdf";
// Save updated document
document.Save(dataDir);

How to Specify PDF Page when Viewing Document

When viewing PDF files in a PDF viewer such as Adobe Reader, the files usually open on the first page. However, it is possible to set the file to open on a different page.

The XYZExplicitDestination class allows you to specify a page in a PDF file that you want to open. When passing the GoToAction object value to the Document class OpenAction property, the document opens at the page specified against the XYZExplicitDestination object. The following code snippet shows how to specify a page as the document open action.

// For complete examples and data files, please go to https://github.com/aspose-pdf/Aspose.PDF-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_AsposePdf_LinksActions();

// Load the PDF file
Document doc = new Document(dataDir + "SpecifyPageWhenViewing.pdf");
// Get the instance of second page of document
Page page2 = doc.Pages[2];
// Create the variable to set the zoom factor of target page
double zoom = 1;
// Create GoToAction instance
GoToAction action = new GoToAction(doc.Pages[2]);
// Go to 2 page
action.Destination = new XYZExplicitDestination(page2, 0, page2.Rect.Height, zoom);
// Set the document open action
doc.OpenAction = action;
// Save updated document
doc.Save(dataDir + "goto2page_out.pdf");