PDF Export > VpeAddBookmark

[VPE Professional Edition and above]

Adds a bookmark to the document: a PDF document may optionally display a document outline on the screen, allowing the user to navigate interactively from one part of the document to another. The outline consists of a tree-structured hierarchy of bookmark items, which serve as a "visual table of contents" to display the document’s structure to the user. Bookmarks are displayed in the left tree-view of Acrobat Reader.

The added bookmark will have the currently assigned destination, style and color (see VpeSetBookmarkDestination(), VpeSetBookmarkStyle(), VpeSetBookmarkColor()).

The target page for the destination is always the currently active page of the VPE document as you call this method.

In order to create a hierarchical tree structure, you can supply a parent bookmark as parent, i.e. the added bookmark will be a child of the supplied parent bookmark. To add a bookmark to the top-level of the hierarchy, specify a value of null for the parent.

The VpeAddBookmark method returns a handle to the newly created bookmark, which can be used as parent for subsequent calls.

VpeHandle VpeAddBookmark(

VpeHandle hDoc,

VpeHandle parent,

LPCSTR title

)

VpeHandle hDoc

Document Handle

VpeHandle parent

the parent bookmark or null for a top-level bookmark

LPCSTR title

the title of the bookmark

Returns:

a handle to the newly created bookmark, which can be used as parent for subsequent calls

Remarks:

Bookmarks are not shown within VPE documents. They are stored internally and are exported to PDF documents only.

Bookmarks are not stored within VPE document files. If you write a VPE document that contains bookmarks to a file, read the file later into memory and export it to PDF, the bookmarks are omitted. For the same reason, bookmarks will be missing in exported PDF files, if the VPE source document is created stream-based by using VpeOpenDocFile().

Example:

// Bold and Italic styles will work only with PDF 1.4, activate it:

VpeSetPDFVersion(hDoc, VPE_PDF_ACROBAT_5);

// Output some text on the current page:

VpePrint(hDoc, 1, 1, "Introduction");

// Set the style for newly added bookmarks to bold, italic, open:

VpeSetBookmarkStyle(hDoc, VBOOKMARK_STYLE_BOLD + VBOOKMARK_STYLE_ITALIC + VBOOKMARK_STYLE_OPEN);

// Set the destination type for newly added bookmarks:

VpeSetBookmarkDestination(hDoc, VBOOKMARK_DEST_FIT, 0, 0, 0, 0, 1);

// Add a new bookmark to the top-level of the hierachy:

VpeHandle ParentBookmark = VpeAddBookmark(hDoc, NULL, "Introduction");

// Append a new page to the VPE document:

VpePageBreak(hDoc);

// Output some text on the current page:

VpePrint(hDoc, 1, 1, "Bookmarks explained");

// Add a new bookmark as child of the previously inserted bookmark.

// It will have the currently adjusted style, color and destination:

VpeAddBookmark(hDoc, ParentBookmark, "Bookmarks explained");