PDFtoolkit VCL
Edit, enhance, secure, merge, split, view, print PDF and AcroForms documents

Compatibility

Delphi C++Builder

Home » Newsletter » November 2009

By V. Subhash

Last month, we released Version 3.4.2 of PDFtoolkit VCL. In this version, we had changed the way bookmarks are created and processed. Here is an excerpt from the history of PDFtoolkit.

…

• Bookmark creation and bookmark tree traversal overhauled.
  • Added new
    • GetByTitle method
    • LastChild property
    • BookmarkIndex property
    • Level property
  • Changed: GetBookmarkRoot returns root bookmark for creating new bookmarks, regardless whether PDF contains bookmarks or not. Redundant and unused method CreateNewBookmark removed.
  • Changed: Deprecated GetFirstChild, GetNextNode, GetPrevNode and AppendChild to avoid confusion with other existing methods for similar functionality

…

Previously, you would have used TgtPDFDocument.GetBookmarkRoot() to check if a document had bookmarks. If there were no bookmarks, the method would return Nil. From this version, the method will return the root bookmark whether or not the document has bookmarks.

Now, all this might may not mean much if you have never explored this feature. If you are interested, the rest of this article will provide an introduction to bookmarks creation and processing.

PDF Bookmarks - A Small Introduction

Bookmarks is an interactive feature of PDF. In a PDF viewer application, bookmarks are displayed in a hierarchical tree. When a user clicks on a bookmark, the viewer application displays a page linked to the bookmark. Thus, bookmarks provide easy navigation to different pages of a document. In other words, they can be used to provide a visual and interactive table of contents for the PDF document.

PDF Bookmarks Processing

At the top of the bookmarks hierarchy is the root bookmark. The root bookmark is a hidden bookmark. It is the parent of all bookmarks that are displayed by a PDF viewer application. To make it more clear, look at it like this - the first visible bookmark in a document is the first child of the root bookmark.

PDF bookmarks are represented by the TgtOutline class. The GetBookmarkRoot method returns an instance of TgtOutline. If you had a PDF document, you can check whether it has bookmarks using the code shown below.

{
 This code example shows how to check for
 the root bookmark in a document.
}
program TgtCustomPDFDocument_GetBookmarkRoot;

{$APPTYPE CONSOLE}

uses
  SysUtils,
  gtPDFDoc, gtCstPDFDoc;

var
  gtPDFDocument1: TgtPDFDocument;
  gtPDFOutline1: TgtPDFOutline;
begin
  // Create a PDF document object
  gtPDFDocument1 := TgtPDFDocument.Create(Nil);

  try
    // Load a document
    gtPDFDocument1.LoadFromFile('input_doc.pdf');

    // Get root bookmark - returns a root bookmark irrespective
    // of whether the document has any visible bookmarks
    gtPDFOutline1 := gtPDFDocument1.GetBookmarkRoot;

    // Check if document has visible bookmarks, that is, 
    // if the root bookmark has any children
    if gtPDFOutline1.Child = Nil then
      Writeln('This document has no bookmarks.')
    else
      begin
       Writeln('This document has bookmarks.');
       Writeln('The first bookmark is: ' + gtPDFOutline1.Child.Title);
      end;

  except on Err:Exception do
    begin
      Writeln('Sorry, an exception was raised. ');
      Writeln(Err.Classname + ': ' + Err.Message);
    end;
  end;

  // Free resources
  gtPDFDocument1.Reset;
  // Destroy PDF document object
  FreeAndNil(gtPDFDocument1);

  Readln;
end.

If no bookmarks are displayed for a document, then it means that the root bookmark has no child bookmarks. If a document has bookmarks, then you can traverse the bookmark tree using Child, Prev, and Next properties of the current TgtPDFOutline object returned by GetBookmarkRoot. You can add bookmarks along the way using AddChild, AddNext, and AddPrev methods. You can delete bookmarks using DeleteChild, DeletePrev, and DeleteNext methods.

You need to specify the text used to display a bookmark by setting the Title property. To specify the page that is linked by a bookmark, you need to use a TgtPDFDestination instance. You can also specify text style and color of the bookmark using a TgtBookmarkAttribute instance.

Instead of navigating to a page, viewer applications can be made to execute a PDF action, such as a JavaScript action, application or document launch action, go-to action, remote go-to action and URI action. (All of these types actions are represented by classes derived from TgtPDFAction class.) To do this, you need set the Action property of the bookmark.

PDF Bookmark Creation

Bookmark do not simply link to a page. The destination of a bookmark is specified by:

• number of page to be displayed,
• location of the viewer window on the page, and
• zoom applied when displaying the page.

The location of the viewer window on the page and the zoom is determined by TgtPDFDestination class. Please refer the help file for in-depth description of the properties of the class.

In the following document, we load a document and add bookmarks for each page in the document.

{
 This code example shows how to add bookmarks
 for each page in a PDF document.
}
program Build_Bookmark_Tree;

{$APPTYPE CONSOLE}

uses
  SysUtils, Graphics,
  gtPDFDoc,
  gtCstPDFDoc;

var
  gtPDFDocument1: TgtPDFDocument;
  gtPDFOutline1: TgtPDFOutline;
  gtPDFDestination1: TgtPDFDestination;
  gtBookmarkAttribute1: TgtBookmarkAttribute;
  i: Integer;
begin
  // Create a PDF document object
  gtPDFDocument1 := TgtPDFDocument.Create(Nil);

  try
    // Load a document
    gtPDFDocument1.LoadFromFile('input_doc4.pdf');

    // Create a bookmark destination
    gtPDFDestination1 := TgtPDFDestination.Create();
    gtPDFDestination1.DestinationType := dtFitH; // Fit entire width of page
    gtPDFDestination1.Top := 100;   // Viewer scrolls 100 points down from top
    gtPDFDestination1.PageNo := 1;  // Navigation to page #1

    // Create a bookmark attribute object
    gtBookmarkAttribute1 := TgtBookmarkAttribute.Create();
    // Use these settings if required
    // gtBookmarkAttribute1.FontStyles := [fsBold];
    // gtBookmarkAttribute1.OutlineColor := clBlack;

    // Get root bookmark - returns a root bookmark irrespective
    // of whether the document has any visible bookmarks
    gtPDFOutline1 := gtPDFDocument1.GetBookmarkRoot;

    // Build bookmarks if there are no bookmarks
    if gtPDFOutline1.Child = Nil then
    begin
      // Add the first bookmark
      gtPDFOutline1 := gtPDFOutline1.AddChild('Page 1',
                                              gtPDFDestination1,
                                              gtBookmarkAttribute1);

      // Add sibling bookmarks for the rest of the pages
      for i := 2 to gtPDFDocument1.PageCount  do
      begin
        gtPDFDestination1.PageNo := i;
        gtPDFOutline1 := gtPDFOutline1.AddNext('Page ' + Inttostr(i),
                                               gtPDFDestination1,
                                               gtBookmarkAttribute1);
      end;

      gtPDFDocument1.SaveToFile('output_doc.pdf');
      Writeln('Bookmark tree has been created.');
    end
    else
      Writeln('This document already has bookmarks.');

  except on Err:Exception do
    begin
      Writeln('Sorry, an exception was raised. ');
      Writeln(Err.Classname + ': ' + Err.Message);
    end;
  end;

  // Free resources
  gtPDFDocument1.Reset;
  // Destroy PDF document object
  FreeAndNil(gtPDFDocument1);

  Writeln('Press Enter to exit.');
  Readln;
end.