Outlines And Bookmarks
When creating a new PDF, outlines and bookmarks can be included in a PDF document that allows quick access to specific pages in a PDF document. Both outlines and bookmarks can be added to a PDF document.
Make sure to distinguish creating an outline or bookmark from scratch from merging existing PDFs containing outlines or bookmarks. Refer to Reading Outlines and Bookmarks for more information on working with outlines and bookmarks when merging PDFs.
Outlines
Add outlines to a document through the Document class's Outlines property. A Document instance's Outlines property is an OutlineList that contains one or more Outline instances. When adding an outline to a PDF, you create individual Outline instances and add them to the Document instance. When adding a child outline to an outline, you add Outline instances to the parent Outline instance's ChildOutlines property. Examples of both are included below.
Outline
When creating a Document, add one or more Outline instances to a Document instance's Outlines property. An Outline has properties for the Outline instance's formatting and properties for working with that Outline instance's parent outlines or child outlines. For example, an Outline has a ChildOutlines property, which is an OutlineList, and thus allows the creation of an outline hierarchy.
Properties
| Property | Description |
|---|---|
| ChildOutlines | Gets a collection or child outlines. |
| Color | Gets or sets the color of the outline. |
| Expanded | Gets or sets a value specifying if the outline is expanded. |
| Parent | Gets the parent of the outline. |
| Style | Gets or sets the style of the outline. |
| Text | Gets or sets the text of the outline. |
Example
An outline is a hierarchical list of outlines associated with a document. This hierarchical nature of outlines should be more apparent after reviewing the following example. In this example, three pages are added to a new document. A top-level outline is created, and outline elements are added to each page. The example also adds a child outline element. The example also includes the ZoomDestination action and XYDestination actions.
Figure 1. Outlines Example
// Create a PDF Document
Document document = new Document();
// Add three blank pages
document.Pages.Add( new Page( PageSize.Letter ) );
document.Pages.Add( new Page( PageSize.Letter ) );
document.Pages.Add( new Page( PageSize.Letter ) );
// Add a top level outline and set properties
Outline outline1 = document.Outlines.Add( "Outline1" );
outline1.Style = TextStyle.Bold;
outline1.Color = new RgbColor( 1.0f, 0.0f, 0.0f );
// Add child outlines
Outline outline1A = outline1.ChildOutlines.Add( "Outline1A", new ZoomDestination( 2, PageZoom.FitPage ) );
outline1A.Expanded = false;
Outline outline1A1 = outline1A.ChildOutlines.Add( "Outline1A1", new XYDestination( 2, 0, 0 ) );
Outline outline1A2 = outline1A.ChildOutlines.Add( "Outline1A2", new ZoomDestination( 2, PageZoom.FitHeight ) );
Outline outline1B = outline1.ChildOutlines.Add( "Outline1B", new ZoomDestination( 2, PageZoom.FitWidth ) );
// Add a second top level outline
Outline outline2 = document.Outlines.Add( "Outline2", new XYDestination( 3, 0, 300 ) );
// Add a child outline
Outline outline2A = outline2.ChildOutlines.Add( "Outline2A" );
// Save the PDF document
document.Draw(pdfFilePath);
' Create a PDF Document
Dim MyDocument As Document = New Document()
' Add three blank pages
MyDocument.Pages.Add( New Page( PageSize.Letter ) )
MyDocument.Pages.Add( New Page( PageSize.Letter ) )
MyDocument.Pages.Add( New Page( PageSize.Letter ) )
' Add a top level outline and set properties
Dim MyOutline1 As Outline = MyDocument.Outlines.Add( "Outline1" )
MyOutline1.Style = TextStyle.Bold
MyOutline1.Color = New RgbColor( 1.0f, 0.0f, 0.0f )
' Add child outlines
Dim MyOutline1A As Outline = MyOutline1.ChildOutlines.Add( "Outline1A", New ZoomDestination( 2, PageZoom.FitPage ) )
MyOutline1A.Expanded = False
Dim MyOutline1A1 As Outline = MyOutline1A.ChildOutlines.Add( "Outline1A1", New XYDestination( 2, 0, 0 ) )
Dim MyOutline1A2 As Outline = MyOutline1A.ChildOutlines.Add( "Outline1A2", New ZoomDestination( 2, PageZoom.FitHeight ) )
Dim MyOutline1B As Outline = MyOutline1.ChildOutlines.Add( "Outline1B", New ZoomDestination( 2, PageZoom.FitWidth ) )
' Add a second top level outline
Dim MyOutline2 As Outline = MyDocument.Outlines.Add( "Outline2", New XYDestination( 3, 0, 300 ) )
' Add a child outline
Dim MyOutline2A As Outline = MyOutline2.ChildOutlines.Add( "Outline2A" )
' Save the PDF document
MyDocument.Draw(pdfFilePath)
Refer to the Outline API documentation for a complete example.
Actions
As the previous example illustrated, an outline element in a PDF can link to an external URL, a location within the PDF, or specify how much to zoom in/out on the page the outline refers to. The location that an outline links to can be specified using an Action instance. The OutlineList class has an Add method that takes an Action instance.
public Outline Add(string text, Action action)
There are three Action classes included with DynamicPDF Core Suite for .NET.
- UrlAction - Links to an external URL.
- XYDestination - Links to an XY coordinate on a page.
- ZoomDestination - Links to a page at a specified zoom level.
The Action class is the parent class to the three classes used by outlines. Refer to the Actions documentation topic for more information on how to use actions.
Bookmarks
Outlines can also be added to the document using the Bookmark class. Instances of this class can add outlines to the document's root or any of the outlines beneath a parent outline. These bookmarks always link to a coordinate on the page that contains them.
When adding a bookmark, you add it to the Page instance's Elements property.
Bookmark
Properties inherited from PageElement are excluded for the the properties table listed here.
Properties
| Property | Description |
|---|---|
| Color | Gets or sets the Color object to use for the text of the bookmark. |
| ParentOutline | Gets or sets the Outline object the bookmark will appear under. |
| Style | Gets or sets the TextStyle enumeration that represents the text style of the bookmark. |
| Text | Gets or sets the text of the bookmark. |
| X | Gets of sets the X coordinate of the bookmark. |
| Y | Gets or sets the Y coordinate of the bookmark. |
Example
// Create a PDF Document
Document document = new Document();
// Create three page objects
Page page1 = new Page( PageSize.Letter );
Page page2 = new Page( PageSize.Letter );
Page page3 = new Page( PageSize.Letter );
// Add a top level Outline
Outline parentOutline = document.Outlines.Add( "Parent Outline" );
// Add a top level bookmark
page1.Elements.Add( new Bookmark( "Top level bookmark to page 1", 0, 0 ) );
// Add child bookmarks
page1.Elements.Add( new Bookmark( "Bookmark to page 1", 0, 0, parentOutline ) );
page2.Elements.Add( new Bookmark( "Bookmark to page 2", 0, 0, parentOutline ) );
page3.Elements.Add( new Bookmark( "Bookmark to page 3", 0, 0, parentOutline ) );
// Add the three pages to the document
document.Pages.Add( page1 );
document.Pages.Add( page2 );
document.Pages.Add( page3 );
// Save the PDF document
document.Draw(pdfFilePath);
' Create a PDF Document
Dim MyDocument As Document = New Document()
' Create three page objects
Dim MyPage1 As Page = New Page( PageSize.Letter )
Dim MyPage2 As Page = New Page( PageSize.Letter )
Dim MyPage3 As Page = New Page( PageSize.Letter )
' Add a top level Outline
Dim MyParentOutline As Outline = MyDocument.Outlines.Add( "Parent Outline" )
' Add a top level bookmark
MyPage1.Elements.Add( New Bookmark( "Top level bookmark to page 1", 0, 0 ) )
' Add child bookmarks
MyPage1.Elements.Add( New Bookmark( "Bookmark to page 1", 0, 0, MyParentOutline ) )
MyPage2.Elements.Add( New Bookmark( "Bookmark to page 2", 0, 0, MyParentOutline ) )
MyPage3.Elements.Add( New Bookmark( "Bookmark to page 3", 0, 0, MyParentOutline ) )
' Add the three pages to the document
MyDocument.Pages.Add( MyPage1 )
MyDocument.Pages.Add( MyPage2 )
MyDocument.Pages.Add( MyPage3 )
' Save the PDF document
MyDocument.Draw(pdfFilePath)