A destination is a view of a document defined by a page number, a page location and a zoom factor. It can be associated with outline items (see section Document Outline) or annotations (see section Annotations).

Functions working with destinations accepts two types of destination:

Here is an example of a destination definition:

destination_str = "mode=XYZ; left=72; right=144; zoom=2.5"

A destination definition consists of a mode and parameters related to that mode. For example, the destination in the example above specifies a view of a page with the coordinates (72, 144) positioned at the upper-left corner of the window and the content of the page magnified to 250%. Refer to Destination Syntax for more details on the destination definition format.

Sometimes a destination can be shared among multiple annotations or outline items. To save some space in the produced PDF document it is better to create a destination object with destination_define():

destination_obj = doc.destination_define("mode=Fit")

Another reason for using a destination object can be forward link annotations (see an example in Annotations).

In the next sections we will show how to associate a destination with outline items and annotations.

A PDF document can optionally include a document outline. It is a tree of outline items (sometimes called bookmarks) which allows the user to quickly move from one part of the document to another.

JagPDF provides class DocumentOutline which allows to form a document outline. We can retrieve its instance from outline():

outline = doc.outline()

So let's create a document with six pages and create an outline item for each page:

for i in [1, 2, 3, 4, 5, 6]:
    doc.page_start(597.6, 848.68)
    outline.item('Go to page %d' % i)
    doc.page_end()

In the previous example we have created a flat document outline. Let's extend our example and form a hierarchy of outline items by with help of level_down() and level_up()

for i in [1, 2, 3, 4, 5, 6]:
    doc.page_start(597.6, 848.68)
    if i % 2:
        outline.item('Go to page %d' % i)
    else:
        outline.level_down()
        outline.item('Go to page %d' % i)
        outline.level_up()
    doc.page_end()

Now, we have made even pages children of odd pages.

The following example illustrates how to associate a destination with an outline item. We will create several outline items representing different views (destinations) of a single page.

doc.page_start(597.6, 848.68)
outline.item('mode XYZ, zoom 300%', 'mode=XYZ; zoom=3.0')
outline.item('mode Fit', 'mode=Fit')
outline.item('mode FitH', 'mode=FitH; top=800')
outline.item('mode FitV', 'mode=FitV; top=0')
doc.page_end()

In certain cases we might want a document outline not to follow the order of pages. For instance, let's create a document outline referring to pages in reverse order:

for i in [1, 2, 3]:
    doc.page_start(597.6, 848.68)
    doc.page_end()
for i in [2, 1, 0]:
    outline.item('Page %d' % (i+1), 'mode=XYZ; page=%d; top=848.68' % i)

The trick is the 'page' option in the destination definition. It explicitly says that we want the destination on that particular page. If we do not specify 'page', as we have done in our examples so far, then the current page is used (assuming we are between page_start() and page_end()). Thus, the 'page' option allows us to create an arbitrary document outline structure regardless of the order of pages.

Summary

PDF allows to annotate a location on a page. Clicking such location invokes behavior inherent to the nature of the annotation. The following sections describe individual annotation types.

font = doc.font_load('standard; name=Helvetica; size=24')
canvas.text_font(font)
x, y = 50, 800
text = 'Click this text to go to page 2.'
canvas.text(x, y, text)

bbox_width = font.advance(text)
bbox_height = font.bbox_ymax() - font.bbox_ymin()

doc.page().annotation_goto(x, y + font.bbox_ymin(),
                           bbox_width, bbox_height,
                           "mode=Fit; page=1")

img = doc.image_load_file('logo.png')
canvas.image(img, 50, 750)

width = img.width() / img.dpi_x() * 72
height =img.height() / img.dpi_y() * 72

doc.page().annotation_uri(50, 750, width, height, "http://jagdpf.org")

doc.page_start(597.6, 848.68)
canvas = doc.page().canvas()
canvas.rectangle(100, 700, 80, 80)
canvas.path_paint('s')

dest = doc.destination_reserve()
doc.page().annotation_goto(100, 700, 80, 80, dest)
doc.page_end()

doc.page_start(597.6, 848.68)
doc.page().canvas().text(50, 300, 'Heading')

doc.destination_define_reserved(dest, "mode=XYZ; top=315")
doc.page_end()

A destination is specified by a string which follows the options string format. The following table lists available destination modes and corresponding parameters:

For details on individual modes see table Destination syntax in the PDF Reference, chapter Interactive Features | Document-Level Navigation | Destinations | Explicit Destinations

The following are examples of valid destination specifications:

'page=0; mode=XYZ; zoom=.5'
'mode=Fit'
'mode=FitBH; top=100'

The mode option is mandatory, other parameters are optional.

Coordinate values (left, right, top and bottom) are expressed in default user space units. If a parameter is not specified then the current value of that parameter is retained unchanged. The only exception is the FitR mode where not specifying any of the parameters may result in unpredictable behavior.

Page numbering is zero based. If the page option is not specified then value of page_number() is used.