LayerPD_Layer
ObjectPDBookmark

A bookmark corresponds to an outline object in a PDF document (see Section 8.2.2, Document Outline, in the PDF Reference). A document outline allows the user to navigate interactively from one part of the document to another. An outline consists of a tree-structured hierarchy of bookmarks, which display the document's structure to the user. Each bookmark has:

Bookmarks can either be created interactively by the user through Acrobat's user interface or can be generated programmatically. The typical action for a user-created bookmark is to move to another location in the current document, although any action (see PDAction) can be specified.

Each bookmark in the bookmark tree structure has zero or more children that appear indented on screen, and zero or more siblings that appear at the same indentation level. All bookmarks except the bookmark at the top level of the hierarchy have one parent, the bookmark under which it is indented. A bookmark is said to be open if its children are visible on screen, and closed if they are not.

A plug-in can get or set:


Typedef Summary
 Typedef
 PDBookmark
A bookmark on a page in a PDF file. Each bookmark has a title that appears on screen, and an action that specifies what happens when a user clicks on the bookmark. Bookmarks can either be created interactively by the user through the Acrobat viewer's user interface or programmatically generated. The typical action for a user-created bookmark is to move to another location in the current document, although any action (see PDAction) can be specified.
Enumeration Summary
 Enumeration
  PDBookmarkFlags
Method Summary
 Method
 
void PDBookmarkAddChild(PDBookmark parent, PDBookmark aBookmark)
Adds aBookmark as the last child of parent, adjusting the tree containing parent appropriately. If parent previously had no children, it is open after the child is added.
 
PDBookmark PDBookmarkAddNewChild(PDBookmark aBookmark, const char* initialText)
Adds a new bookmark to the tree containing aBookmark, as the new last child of aBookmark. If aBookmark previously had no children, it will be open after the child is added.
 
PDBookmark PDBookmarkAddNewChildASText(PDBookmark aBookmark, const ASText initialText)
Adds a new bookmark to the tree containing aBookmark, as the new last child of aBookmark. If aBookmark previously had no children, it will be open after the child is added.
 
PDBookmark PDBookmarkAddNewSibling(PDBookmark aBookmark, char* initialText)
Adds a new bookmark to the tree containing aBookmark, as the new right sibling.
 
PDBookmark PDBookmarkAddNewSiblingASText(PDBookmark aBookmark, const ASText initialText)
Adds a new bookmark to the tree containing aBookmark, as the new right sibling.
 
void PDBookmarkAddNext(PDBookmark aBookmark, PDBookmark newNext)
Adds newNext as the new right sibling to aBookmark.
 
void PDBookmarkAddPrev(PDBookmark aBookmark, PDBookmark newPrev)
Adds newPrev as the new left sibling to aBookmark, adjusting the tree containing aBookmark appropriately.
 
void PDBookmarkAddSubtree(PDBookmark aBookmark, PDBookmark source, char* sourceTitle)
Adds a copy of the bookmark subtree source to aBookmark, as a new last child of aBookmark. This new item will have the text value sourceTitle, will be open, and will have no destination attribute. source must have been previously unlinked. If aBookmark previously had no children, it will be open after the subtree is added.
 
void PDBookmarkAddSubtreeASText(PDBookmark aBookmark, PDBookmark source, const ASText sourceTitle)
Adds a copy of the bookmark subtree source to aBookmark, as a new last child of aBookmark. This new item will have the text value sourceTitle, will be open, and will have no destination attribute. source must have been previously unlinked. If aBookmark previously had no children, it will be open after the subtree is added.
 
void PDBookmarkDestroy(PDBookmark aBookmark)
Removes a bookmark subtree from the bookmark tree containing it.
 
void PDBookmarkDidChange(PDBookmark bookmark, ASAtom key, ASInt32 err, void* clientData)
A bookmark has been opened/closed, its action has been changed, its title has been changed, or children have been added to it.
 
void PDBookmarkDidChangeOpenState(PDBookmark bookmark, ASBool open, void* clientData)
A bookmark was opened or closed.
 
void PDBookmarkDidChangePosition(PDBookmark bookmark, void* clientData)
One or more bookmarks have been moved.
 
void PDBookmarkDidDestroy(PDBookmark bookmark, ASInt32 err, void* clientData)
A bookmark was destroyed.
 
void PDBookmarkDidUnlink(PDBookmark bookmark, void* clientData)
A bookmark was unlinked from the bookmark tree.
 
ASBool PDBookmarkEqual(PDBookmark aBookmark, PDBookmark bookmark2)
Tests whether two bookmarks are equal. Two bookmarks are equal only if their Cos objects are equal (see CosObjEqual()).
 
PDBookmark PDBookmarkFromCosObj(CosObj obj)
Converts a Cos dictionary object to a bookmark and checks the validity of the bookmark. This method does not copy the object, but is instead the logical equivalent of a type cast.
 
PDAction PDBookmarkGetAction(PDBookmark aBookmark)
Gets a bookmark's action. After you obtain the action, you can execute it with AVDocPerformAction().
 
PDBookmark PDBookmarkGetByTitle(PDBookmark aBookmark, const char* aname, ASInt32 nameLen, ASInt32 maxdepth)
Gets the first bookmark whose title is aName.
 
PDBookmark PDBookmarkGetByTitleASText(PDBookmark aBookmark, const ASText title, ASInt32 maxDepth)
Gets the first bookmark whose title is set in passed the ASText object.
 
ASBool PDBookmarkGetColor(PDBookmark bm, PDColorValue pdcvOut)
Retrieves the color of the specified bookmark.
 
CosObj PDBookmarkGetCosObj(PDBookmark aBookmark)
Gets the Cos object for a bookmark. This method does not copy the object, but is instead the logical equivalent of a type cast.
 
ASInt32 PDBookmarkGetCount(PDBookmark aBookmark)
Gets the number of open bookmarks in a subtree.
 
PDBookmark PDBookmarkGetFirstChild(PDBookmark aBookmark)
Gets a bookmark's first child.
 
ASInt32 PDBookmarkGetFlags(PDBookmark bm)
Retrieves the flags of the specified bookmark.
 
ASInt32 PDBookmarkGetIndent(PDBookmark aBookmark)
Returns the indentation level of a bookmark in its containing tree.
 
PDBookmark PDBookmarkGetLastChild(PDBookmark aBookmark)
Gets a bookmark's last child.
 
PDBookmark PDBookmarkGetNext(PDBookmark aBookmark)
Gets a bookmark's next (right) sibling.
 
PDBookmark PDBookmarkGetParent(PDBookmark aBookmark)
Gets a bookmark's parent bookmark.
 
PDBookmark PDBookmarkGetPrev(PDBookmark aBookmark)
Returns a bookmark's previous (left) sibling.
 
ASInt32 PDBookmarkGetTitle(PDBookmark aBookmark, char* buffer, ASInt32 bufSize)
Gets a bookmark's title.
 
void PDBookmarkGetTitleASText(PDBookmark aBookmark, ASText title)
Gets a bookmark's title as an ASText object.
 
ASBool PDBookmarkHasChildren(PDBookmark aBookmark)
Tests whether a bookmark has children.
 
ASBool PDBookmarkIsOpen(PDBookmark aBookmark)
Tests whether a bookmark is open. An open bookmark shows all its children.
 
ASBool PDBookmarkIsValid(PDBookmark aBookmark)
Tests whether a bookmark is valid. This is intended only to ensure that the bookmark has not been deleted, not to ensure that all necessary information is present and valid.
 
void PDBookmarkRemoveAction(PDBookmark aBookmark)
Removes a bookmark's action.
 
void PDBookmarkSetAction(PDBookmark aBookmark, PDAction action)
Sets a bookmark's action.
 
void PDBookmarkSetColor(PDBookmark bm, PDColorValue pdcvIn)
Sets the color of the specified bookmark.
 
void PDBookmarkSetFlags(PDBookmark bm, ASInt32 nFlags)
Sets the flags of the specified bookmark.
 
void PDBookmarkSetOpen(PDBookmark aBookmark, ASBool isOpen)
Opens or closes a bookmark. An open bookmark shows its children, while a closed bookmark does not.
 
void PDBookmarkSetTitle(PDBookmark aBookmark, const char* str, ASInt32 nBytes)
Sets a bookmark's title.
 
void PDBookmarkSetTitleASText(PDBookmark aBookmark, const ASText title)
Sets a bookmark's title.
 
void PDBookmarkUnlink(PDBookmark aBookmark)
Unlinks a bookmark from the bookmark tree that contains it, and adjusts the tree appropriately.
 
void PDBookmarkWasCreated(PDBookmark bookmark, void* clientData)
A bookmark was created.
 
void PDBookmarkWillChange(PDBookmark bookmark, ASAtom key, void* clientData)
A bookmark will be opened or closed, its action will be changed, its title will be changed, or children will be added to it.
 
void PDBookmarkWillChangeOpenState(PDBookmark bookmark, ASBool open, void* clientData)
A bookmark will be opened or closed.
 
void PDBookmarkWillDestroy(PDBookmark bookmark, void* clientData)
A bookmark will be destroyed.

Typedefs Detail
PDBookmark 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef OPAQUE_64_BITS PDBookmark;

A bookmark on a page in a PDF file. Each bookmark has a title that appears on screen, and an action that specifies what happens when a user clicks on the bookmark. Bookmarks can either be created interactively by the user through the Acrobat viewer's user interface or programmatically generated. The typical action for a user-created bookmark is to move to another location in the current document, although any action (see PDAction) can be specified.

See Also

PDDocGetBookmarkRoot
PDBookmarkAddNewSibling
PDBookmarkAddNewChild
PDBookmarkFromCosObj
PDBookmarkGetByTitle
PDBookmarkGetParent
PDBookmarkGetFirstChild
PDBookmarkGetLastChild
PDBookmarkGetNext
PDBookmarkGetPrev
PDBookmarkDestroy
PDBookmarkUnlink

File: PDExpT.h
Line: 1083

Enumeration Detail
PDBookmarkFlags
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

enum PDBookmarkFlags {
 kPDBookmarkFontNormal = 0x00,
 
 kPDBookmarkFontItalic = 0x01,
 
 kPDBookmarkFontBold = 0x02,
 
 kPDBookmarkFontBoldItalic = 0x03
}

File: PDExpT.h
Line: 1089



Method Detail
PDBookmarkAddChild()
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkAddChild(PDBookmark parent, PDBookmark aBookmark)

Adds aBookmark as the last child of parent, adjusting the tree containing parent appropriately. If parent previously had no children, it is open after the child is added.

Parameters

parent — 

The parent of the bookmark being added.
 
aBookmark — 

The bookmark that will become the last child of aBookmark. aBookmark must have been previously unlinked.

See Also

PDBookmarkAddNewSibling
PDBookmarkAddNewChild
PDBookmarkAddSubtree
PDBookmarkAddPrev
PDBookmarkAddNext
PDBookmarkUnlink

Notifications

PDBookmarkDidChangePosition

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 909
PDBookmarkAddNewChild() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDBookmark PDBookmarkAddNewChild(PDBookmark aBookmark, const char* initialText)

Adds a new bookmark to the tree containing aBookmark, as the new last child of aBookmark. If aBookmark previously had no children, it will be open after the child is added.

Parameters

aBookmark — 

The bookmark to which a new last child is added.

 
initialText — 

The new bookmark's title.

Returns

The newly created bookmark.

See Also

PDBookmarkAddNewSibling
PDBookmarkAddSubtree
PDBookmarkAddPrev
PDBookmarkAddNext
PDBookmarkAddChild
PDBookmarkUnlink

Notifications

PDBookmarkDidChangePosition
PDBookmarkWasCreated

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 773
PDBookmarkAddNewChildASText() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDBookmark PDBookmarkAddNewChildASText(PDBookmark aBookmark, const ASText initialText)

Adds a new bookmark to the tree containing aBookmark, as the new last child of aBookmark. If aBookmark previously had no children, it will be open after the child is added.

Parameters

aBookmark — 

The bookmark to which a new last child is added.

 
initialText — 

The text object containing the new bookmark's title.

Returns

The newly created bookmark.

See Also

PDBookmarkAddNewChild
PDBookmarkAddNewSiblingASText
PDBookmarkAddNewSibling
PDBookmarkAddSubtreeASText
PDBookmarkAddSubtree
PDBookmarkAddPrev
PDBookmarkAddNext
PDBookmarkAddChild
PDBookmarkUnlink

Notifications

PDBookmarkDidChangePosition
PDBookmarkWasCreated

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h
Line: 11490
PDBookmarkAddNewSibling() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDBookmark PDBookmarkAddNewSibling(PDBookmark aBookmark, char* initialText)

Adds a new bookmark to the tree containing aBookmark, as the new right sibling.

Parameters

aBookmark — 

The bookmark that will be the left sibling of the new bookmark.

 
initialText — 

The new bookmark's title.

Returns

The newly created bookmark.

See Also

PDBookmarkAddChild
PDBookmarkAddNewChild
PDBookmarkAddNext
PDBookmarkAddPrev
PDBookmarkAddSubtree
PDBookmarkUnlink

Notifications

PDBookmarkDidChangePosition
PDBookmarkWasCreated

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 752
PDBookmarkAddNewSiblingASText() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDBookmark PDBookmarkAddNewSiblingASText(PDBookmark aBookmark, const ASText initialText)

Adds a new bookmark to the tree containing aBookmark, as the new right sibling.

Parameters

aBookmark — 

The bookmark that will be the left sibling of the new bookmark.

 
initialText — 

The text object containing the new bookmark's title.

Returns

The newly created bookmark.

See Also

PDBookmarkAddNewSibling
PDBookmarkAddChild
PDBookmarkAddNewChildASText
PDBookmarkAddNewChild
PDBookmarkAddNext
PDBookmarkAddPrev
PDBookmarkAddSubtreeASText
PDBookmarkAddSubtree
PDBookmarkUnlink

Notifications

PDBookmarkDidChangePosition
PDBookmarkWasCreated

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h
Line: 11464
PDBookmarkAddNext() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkAddNext(PDBookmark aBookmark, PDBookmark newNext)

Adds newNext as the new right sibling to aBookmark.

Parameters

aBookmark — 

IN/OUT The bookmark that will receive a new right sibling.

 
newNext — 

IN/OUT The bookmark to become the new right sibling of aBookmark. newNext must have been previously unlinked.

See Also

PDBookmarkAddNewSibling
PDBookmarkAddChild
PDBookmarkAddSubtree
PDBookmarkAddPrev
PDBookmarkAddNewChild
PDBookmarkUnlink

Notifications

PDBookmarkDidChangePosition

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 889
PDBookmarkAddPrev() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkAddPrev(PDBookmark aBookmark, PDBookmark newPrev)

Adds newPrev as the new left sibling to aBookmark, adjusting the tree containing aBookmark appropriately.

Parameters

aBookmark — 

The bookmark that will receive a new left sibling newPrev.

 
newPrev — 

The bookmark to become the new left sibling of aBookmark. newPrev must have been previously unlinked.

See Also

PDBookmarkAddNewSibling
PDBookmarkAddNewChild
PDBookmarkAddSubtree
PDBookmarkAddNext
PDBookmarkAddChild
PDBookmarkUnlink

Notifications

PDBookmarkDidChangePosition

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 871
PDBookmarkAddSubtree() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkAddSubtree(PDBookmark aBookmark, PDBookmark source, char* sourceTitle)

Adds a copy of the bookmark subtree source to aBookmark, as a new last child of aBookmark. This new item will have the text value sourceTitle, will be open, and will have no destination attribute. source must have been previously unlinked. If aBookmark previously had no children, it will be open after the subtree is added.

Parameters

aBookmark — 

IN/OUT The bookmark to which the subtree source will be added as a new last child.

 
source — 

IN/OUT The bookmark subtree to add.

 
sourceTitle — 

IN/OUT The new bookmark's title.

See Also

PDBookmarkAddNewSibling
PDBookmarkAddNewChild
PDBookmarkAddPrev
PDBookmarkAddNext
PDBookmarkAddChild
PDBookmarkUnlink

Notifications

PDBookmarkWillChange
PDBookmarkDidChange
PDBookmarkDidChangePosition

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 797
PDBookmarkAddSubtreeASText() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkAddSubtreeASText(PDBookmark aBookmark, PDBookmark source, const ASText sourceTitle)

Adds a copy of the bookmark subtree source to aBookmark, as a new last child of aBookmark. This new item will have the text value sourceTitle, will be open, and will have no destination attribute. source must have been previously unlinked. If aBookmark previously had no children, it will be open after the subtree is added.

Parameters

aBookmark — 

The bookmark to which the subtree source will be added as a new last child.

 
source — 

The bookmark subtree to add.

 
sourceTitle — 

The text object containing the new bookmark's title.

See Also

PDBookmarkAddSubtree
PDBookmarkAddNewSiblingASText
PDBookmarkAddNewSibling
PDBookmarkAddNewChildASText
PDBookmarkAddNewChild
PDBookmarkAddPrev
PDBookmarkAddNext
PDBookmarkAddChild
PDBookmarkUnlink

Notifications

PDBookmarkWillChange
PDBookmarkDidChange
PDBookmarkDidChangePosition

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h
Line: 11519
PDBookmarkDestroy() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkDestroy(PDBookmark aBookmark)

Removes a bookmark subtree from the bookmark tree containing it.

Parameters

aBookmark — 

IN/OUT The root bookmark of the subtree to remove.

See Also

PDBookmarkAddNewChild
PDBookmarkAddNewSibling
PDBookmarkFromCosObj
PDBookmarkUnlink

Notifications

PDBookmarkWillDestroy
PDBookmarkDidDestroy

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 812
PDBookmarkDidChange() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkDidChange(PDBookmark bookmark, ASAtom key, ASInt32 err, void* clientData)

A bookmark has been opened/closed, its action has been changed, its title has been changed, or children have been added to it.

Parameters

bookmark — 

The bookmark that will be changed.

 
key — 

The ASAtom specifying the change that will occur. See PDBookmarkWillChange() for a list of the ASAtom objects and their meaning.

 
err — 

The error code. err is set to 0 if no errors occurred while changing the bookmark. If an error occurred, err contains the error code.

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification().

See Also

PDBookmarkSetOpen
PDBookmarkSetAction
PDBookmarkSetTitle
PDBookmarkAddSubtree

Notifications

PDBookmarkWillChange
PDBookmarkDidChangePosition

File: PIPokes.h
Line: 1089
PDBookmarkDidChangeOpenState() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkDidChangeOpenState(PDBookmark bookmark, ASBool open, void* clientData)

A bookmark was opened or closed.

Parameters

bookmark — 

The bookmark that was opened or closed.

 
open — 

When true, the bookmark was opened. When false, it was closed.

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification().

See Also

PDBookmarkSetOpen

Notifications

PDBookmarkWillChange
PDBookmarkDidChange

File: PIPokes.h
Line: 2274
PDBookmarkDidChangePosition() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkDidChangePosition(PDBookmark bookmark, void* clientData)

One or more bookmarks have been moved.

Parameters

bookmark — 

The bookmark that was moved.

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification().

See Also

PDBookmarkAddNext
PDBookmarkAddPrev
PDBookmarkAddNewChild
PDBookmarkAddNewSibling
PDBookmarkAddChild
PDBookmarkAddSubtree

Notifications

PDBookmarkWillChange
PDBookmarkDidChange

File: PIPokes.h
Line: 1036
PDBookmarkDidDestroy() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkDidDestroy(PDBookmark bookmark, ASInt32 err, void* clientData)

A bookmark was destroyed.

Parameters

bookmark — 

The bookmark that was destroyed. Because the bookmark has been destroyed, it is not possible to access it.

 
err — 

The error code. err is set to 0 if no errors occurred while destroying the bookmark. If an error occurred, err contains the error code.

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification().

Notifications

PDBookmarkWillDestroy PDBookmarkDestroy

File: PIPokes.h
Line: 1115
PDBookmarkDidUnlink() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkDidUnlink(PDBookmark bookmark, void* clientData)

A bookmark was unlinked from the bookmark tree.

Parameters

bookmark — 

The bookmark that was unlinked. Because the bookmark has not been destroyed, it is possible to access it.

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification().

Notifications

PDBookmarkDidChangePosition PDBookmarkUnlink

File: PIPokes.h
Line: 1797
PDBookmarkEqual() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDBookmarkEqual(PDBookmark aBookmark, PDBookmark bookmark2)

Tests whether two bookmarks are equal. Two bookmarks are equal only if their Cos objects are equal (see CosObjEqual()).

Parameters

aBookmark — 

The first bookmark to compare.

 
bookmark2 — 

The second bookmark to compare.

Returns

true if the bookmarks are equal, false otherwise.

See Also

CosObjEqual

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 1140
PDBookmarkFromCosObj() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDBookmark PDBookmarkFromCosObj(CosObj obj)

Converts a Cos dictionary object to a bookmark and checks the validity of the bookmark. This method does not copy the object, but is instead the logical equivalent of a type cast.

Parameters

obj — 

The dictionary Cos object whose bookmark is obtained.

Returns

The bookmark corresponding to the Cos object.

See Also

PDBookmarkGetCosObj

Exceptions

pdErrBadBookmark is raised if the bookmark is not valid as determined by PDBookmarkIsValid().

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 1169
PDBookmarkGetAction() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDAction PDBookmarkGetAction(PDBookmark aBookmark)

Gets a bookmark's action. After you obtain the action, you can execute it with AVDocPerformAction().

Parameters

aBookmark — 

IN/OUT The bookmark whose action is obtained.

Returns

The bookmark's action.

See Also

AVDocPerformAction
PDBookmarkSetAction
PDLinkAnnotGetAction

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 1116
PDBookmarkGetByTitle() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDBookmark PDBookmarkGetByTitle(PDBookmark aBookmark, const char* aname, ASInt32 nameLen, ASInt32 maxdepth)

Gets the first bookmark whose title is aName.

Parameters

aBookmark — 

IN/OUT The root of the bookmark subtree to search.

 
aname — 

IN/OUT The text value to search for. Character codes in aName are interpreted using the PDFDocEncoding.

 
nameLen — 

IN/OUT The length of aName.

 
maxdepth — 

IN/OUT The number of subtree levels to search, not counting the root level:

Value

Description

0

Only look at aBookmark, not at any of its children.

1

Check aBookmark and its children, but not any grandchildren or great grandchildren, and so on.

-1

Check the entire subtree.

Returns

The bookmark with the specified title, or a NULL Cos object if there is no such bookmark.

Since

PI_PDMODEL_VERSION >= 0x00020000

Note

For Roman viewers, this text is always stored in the PDFDocEncoding. For non-Roman character set viewers, this text is stored as PDFDocEncoding or Unicode, depending on the file's creator. Files created in a non-Roman environment contain Unicode versions of these strings; in a Roman environment, files contain PDFDocEncoding versions of these strings.

File: PDProcs.h
Line: 842
PDBookmarkGetByTitleASText() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDBookmark PDBookmarkGetByTitleASText(PDBookmark aBookmark, const ASText title, ASInt32 maxDepth)

Gets the first bookmark whose title is set in passed the ASText object.

Parameters

aBookmark — 

The root of the bookmark subtree to search.

 
title — 

The text object containing the title value to search for.

 
maxDepth — 

The number of subtree levels to search, not counting the root level.

Value

Description

0

Only look at aBookmark, not at any of its children.

1

Check aBookmark and its children, but not any grandchildren or great grandchildren, and so on.

-1

Check the entire subtree.

Returns

The bookmark with the specified title, or a NULL Cos object if there is no such bookmark.

See Also

PDBookmarkGetByTitle

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h
Line: 11542
PDBookmarkGetColor() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDBookmarkGetColor(PDBookmark bm, PDColorValue pdcvOut)

Retrieves the color of the specified bookmark.

An exception is thrown if the bookmark is invalid or the existing color is malformed in the PDF file.

Parameters

bm — 

The bookmark in question.

 
pdcvOut — 

(Filled by the method) The color of the bookmark in PDColorValue format.

Returns

true if the color was specified, false otherwise (the default color is returned in pdcvOut).

See Also

PDBookmarkSetColor

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h
Line: 7936
PDBookmarkGetCosObj() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

CosObj PDBookmarkGetCosObj(PDBookmark aBookmark)

Gets the Cos object for a bookmark. This method does not copy the object, but is instead the logical equivalent of a type cast.

Parameters

aBookmark — 

IN/OUT The bookmark whose Cos object is obtained.

Returns

The dictionary Cos object for the bookmark. The contents of the dictionary can be enumerated using CosObjEnum().

See Also

PDBookmarkFromCosObj
CosObjEnum

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 1154
PDBookmarkGetCount() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASInt32 PDBookmarkGetCount(PDBookmark aBookmark)

Gets the number of open bookmarks in a subtree.

Parameters

aBookmark — 

The root bookmark of a subtree to count.

Returns

The number of open bookmarks in the subtree (not including aBookmark).

See Also

PDBookmarkGetIndent
PDBookmarkHasChildren

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 853
PDBookmarkGetFirstChild() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDBookmark PDBookmarkGetFirstChild(PDBookmark aBookmark)

Gets a bookmark's first child.

Parameters

aBookmark — 

IN/OUT The bookmark whose first child is obtained.

Returns

The first child of aBookmark, or a NULL Cos object if aBookmark has no children.

See Also

PDBookmarkGetParent
PDBookmarkGetLastChild
PDBookmarkHasChildren
PDBookmarkGetNext
PDBookmarkGetPrev

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 959
PDBookmarkGetFlags() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASInt32 PDBookmarkGetFlags(PDBookmark bm)

Retrieves the flags of the specified bookmark.

An exception is thrown if the bookmark is invalid or the existing style is malformed in the PDF file.

Parameters

bm — 

The bookmark whose flags are obtained.

Returns

The bookmark's flags. Bit 1 (the least significant bit) indicates an italic font; bit 2 indicates a bold font.

See Also

PDBookmarkSetFlags

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h
Line: 7962
PDBookmarkGetIndent() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASInt32 PDBookmarkGetIndent(PDBookmark aBookmark)

Returns the indentation level of a bookmark in its containing tree.

Parameters

aBookmark — 

IN/OUT The bookmark whose indentation level is obtained.

Returns

The indentation level of aBookmark in its containing tree. The root and its direct children have an indentation level of zero.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 1013
PDBookmarkGetLastChild() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDBookmark PDBookmarkGetLastChild(PDBookmark aBookmark)

Gets a bookmark's last child.

Parameters

aBookmark — 

IN/OUT The bookmark whose last child is obtained.

Returns

The last child of aBookmark, or a NULL Cos object if aBookmark has no children.

See Also

PDBookmarkGetParent
PDBookmarkGetFirstChild
PDBookmarkGetNext
PDBookmarkGetPrev

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 973
PDBookmarkGetNext() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDBookmark PDBookmarkGetNext(PDBookmark aBookmark)

Gets a bookmark's next (right) sibling.

Parameters

aBookmark — 

The bookmark whose right sibling is obtained.

Returns

The aBookmark object's next (right) sibling. It returns a NULL Cos object if aBookmark has no next sibling (that is, it is its parent's last child).

See Also

PDBookmarkGetParent
PDBookmarkGetFirstChild
PDBookmarkGetLastChild
PDBookmarkGetPrev

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 987
PDBookmarkGetParent() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDBookmark PDBookmarkGetParent(PDBookmark aBookmark)

Gets a bookmark's parent bookmark.

Parameters

aBookmark — 

The bookmark whose parent is obtained.

Returns

The parent bookmark of aBookmark, or a NULL Cos object if aBookmark is the root of its tree.

See Also

PDBookmarkGetFirstChild
PDBookmarkGetLastChild
PDBookmarkGetNext
PDBookmarkGetPrev

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 944
PDBookmarkGetPrev() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDBookmark PDBookmarkGetPrev(PDBookmark aBookmark)

Returns a bookmark's previous (left) sibling.

Parameters

aBookmark — 

IN/OUT The bookmark whose left sibling is obtained.

Returns

Previous (left) sibling of aBookmark, or a NULL Cos object if aBookmark has no previous sibling (it is its parent's first child).

See Also

PDBookmarkGetParent
PDBookmarkGetFirstChild
PDBookmarkGetLastChild
PDBookmarkGetNext

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 1002
PDBookmarkGetTitle() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASInt32 PDBookmarkGetTitle(PDBookmark aBookmark, char* buffer, ASInt32 bufSize)

Gets a bookmark's title.

Parameters

aBookmark — 

The bookmark whose title is obtained.
 
buffer — 

(Filled by the method) The buffer into which the title will be written. If buffer is non-NULL, its length is assumed to be bufSize + 1, because a NULL byte is appended to the title. The returned text remains valid only until the next PDModel method call. The text may be converted to a platform's native encoding using PDXlateToHost() or PDXlateToHostEx().
 
bufSize — 

The size of the buffer.

Returns

The number of bytes copied into buffer, not counting the trailing NULL byte. If buffer is NULL, the number of bytes in the bookmark is returned.

See Also

PDBookmarkSetTitle
PDXlateToHost
PDXlateToHostEx

Since

PI_PDMODEL_VERSION >= 0x00020000

Note

For Roman viewers, this title text is always stored in PDFDocEncoding. For non-Roman character set viewers, this text is stored as PDFDocEncoding or Unicode, depending on the file's creator. Files created in a non-Roman environment contain Unicode versions of these strings; in a Roman environment, files contain PDFDocEncoding versions of these strings.

File: PDProcs.h
Line: 1044
PDBookmarkGetTitleASText() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkGetTitleASText(PDBookmark aBookmark, ASText title)

Gets a bookmark's title as an ASText object.

Parameters

aBookmark — 

The bookmark whose title is obtained.

 
title — 

(Filled by the method) The text object containing the title. The client must pass a valid ASText object title. The routine does not allocate it.

See Also

PDBookmarkGetTitle
PDBookmarkSetTitleASText
PDBookmarkSetTitle
PDXlateToHost
PDXlateToHostEx

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h
Line: 11421
PDBookmarkHasChildren() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDBookmarkHasChildren(PDBookmark aBookmark)

Tests whether a bookmark has children.

Parameters

aBookmark — 

The bookmark to test.

Returns

true if aBookmark has any children, false otherwise.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 1080
PDBookmarkIsOpen() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDBookmarkIsOpen(PDBookmark aBookmark)

Tests whether a bookmark is open. An open bookmark shows all its children.

Parameters

aBookmark — 

The bookmark to test.

Returns

true if the bookmark is open, false otherwise.

See Also

PDBookmarkSetOpen

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 1090
PDBookmarkIsValid() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDBookmarkIsValid(PDBookmark aBookmark)

Tests whether a bookmark is valid. This is intended only to ensure that the bookmark has not been deleted, not to ensure that all necessary information is present and valid.

Parameters

aBookmark — 

The bookmark whose validity is tested.

Returns

true if the bookmark is valid, false otherwise.

See Also

PDBookmarkEqual

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 931
PDBookmarkRemoveAction() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkRemoveAction(PDBookmark aBookmark)

Removes a bookmark's action.

Parameters

aBookmark — 

The bookmark whose action is removed.

Exceptions

pdErrBadAction

Notifications

PDBookmarkDidChange
PDBookmarkWillChange

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h
Line: 7797
PDBookmarkSetAction() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkSetAction(PDBookmark aBookmark, PDAction action)

Sets a bookmark's action.

Parameters

aBookmark — 

IN/OUT The bookmark whose action is set.

 
action — 

IN/OUT The bookmark's action.

See Also

PDBookmarkGetAction

Notifications

PDBookmarkWillChange
PDBookmarkDidChange

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 1127
PDBookmarkSetColor() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkSetColor(PDBookmark bm, PDColorValue pdcvIn)

Sets the color of the specified bookmark.

Parameters

bm — 

The bookmark whose color is set.

 
pdcvIn — 

The new color. It must be in DeviceRGB.

See Also

PDBookmarkGetColor

Exceptions

If color is NULL or not in DeviceRGB, the bookmark is invalid or the existing bookmark color is malformed.

Notifications

PDBookmarkWillChange with C as the key.
PDBookmarkDidChange with C as the key.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 7949
PDBookmarkSetFlags() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkSetFlags(PDBookmark bm, ASInt32 nFlags)

Sets the flags of the specified bookmark.

An exception is thrown if the bookmark is invalid or the existing style is malformed in the PDF file.

Parameters

bm — 

The bookmark whose flags are set.

 
nFlags — 

The new bookmark flags. Bit 1 (the least significant bit) indicates an italic font; bit 2 indicates a bold font.

See Also

PDBookmarkGetFlags

Notifications

PDBookmarkWillChange with F as the key.
PDBookmarkDidChange with F as the key

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h
Line: 7977
PDBookmarkSetOpen() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkSetOpen(PDBookmark aBookmark, ASBool isOpen)

Opens or closes a bookmark. An open bookmark shows its children, while a closed bookmark does not.

Parameters

aBookmark — 

IN/OUT The bookmark to open or close.

 
isOpen — 

IN/OUT true if the bookmark is opened, false if the bookmark is closed.

See Also

PDBookmarkIsOpen

Notifications

PDBookmarkWillChange
PDBookmarkDidChange

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 1103
PDBookmarkSetTitle() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkSetTitle(PDBookmark aBookmark, const char* str, ASInt32 nBytes)

Sets a bookmark's title.

Parameters

aBookmark — 

The bookmark whose title is set.

 
str — 

A read-only string containing the bookmark's new title. The text must be encoded using PDFDocEncoding. Strings encoded using a platform's native encoding can be converted to PDFDocEncoding using PDXlateToPDFDocEnc() or PDXlateToPDFDocEncEx().

 
nBytes — 

The number of bytes of str to copy.

See Also

PDBookmarkGetTitle

Exceptions

pdErrBookmarksError is raised if there is an error setting the title.

Notifications

PDBookmarkWillChange
PDBookmarkDidChange

Since

PI_PDMODEL_VERSION >= 0x00020000

Note

For Roman viewers, this title text is always stored in the PDFDocEncoding. For non-Roman character set viewers, this text is stored as PDFDocEncoding or Unicode, depending on the file's creator. Files created in a non-Roman environment contain Unicode versions of these strings; in a Roman environment, files contain PDFDocEncoding versions of these strings.

File: PDProcs.h
Line: 1071
PDBookmarkSetTitleASText() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkSetTitleASText(PDBookmark aBookmark, const ASText title)

Sets a bookmark's title.

Parameters

aBookmark — 

The bookmark whose title is set.

 
title — 

The text object containing the bookmark's new title.

See Also

PDBookmarkSetTitle
PDBookmarkGetTitleASText
PDBookmarkGetTitle

Exceptions

pdErrBookmarksError is raised if there is an error setting the title.

Notifications

PDBookmarkWillChange
PDBookmarkDidChange

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h
Line: 11439
PDBookmarkUnlink() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkUnlink(PDBookmark aBookmark)

Unlinks a bookmark from the bookmark tree that contains it, and adjusts the tree appropriately.

Parameters

aBookmark — 

IN/OUT The bookmark to unlink.

See Also

PDBookmarkDestroy

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 918
PDBookmarkWasCreated() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkWasCreated(PDBookmark bookmark, void* clientData)

A bookmark was created.

Parameters

bookmark — 

The bookmark that was created.

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification().

See Also

PDBookmarkAddNewChild
PDBookmarkAddNewSibling

Notifications

PDBookmarkDidDestroy
PDBookmarkWillDestroy

File: PIPokes.h
Line: 1019
PDBookmarkWillChange() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkWillChange(PDBookmark bookmark, ASAtom key, void* clientData)

A bookmark will be opened or closed, its action will be changed, its title will be changed, or children will be added to it.

Parameters

bookmark — 

The bookmark that will be changed.

 
key — 

The ASAtom specifying the change that will occur. key will be an ASAtom corresponding to one of the following:

key

Description

Count

Children will be added, or the bookmark will be opened or closed.

A

The action will be changed.

Title

The title will be changed.

C

The color will be changed (PDF 1.4).

F

The flags will be changed (PDF 1.4).

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification().

See Also

PDBookmarkSetOpen
PDBookmarkSetAction
PDBookmarkSetTitle
PDBookmarkAddSubtree

Notifications

PDBookmarkDidChange
PDBookmarkDidChangePosition

File: PIPokes.h
Line: 1066
PDBookmarkWillChangeOpenState() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkWillChangeOpenState(PDBookmark bookmark, ASBool open, void* clientData)

A bookmark will be opened or closed.

Parameters

bookmark — 

The bookmark that will be opened or closed.

 
open — 

When true, the bookmark will be opened. When false, it will be closed.

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification().

See Also

PDBookmarkSetOpen

Notifications

PDBookmarkWillChange
PDBookmarkDidChange

File: PIPokes.h
Line: 2261
PDBookmarkWillDestroy() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDBookmarkWillDestroy(PDBookmark bookmark, void* clientData)

A bookmark will be destroyed.

Parameters

bookmark — 

The bookmark that will be destroyed.

 
clientData — 

A pointer to a block of user-supplied data that was passed when the client registered for this notification using AVAppRegisterNotification().

See Also

PDBookmarkDestroy

Notifications

PDBookmarkDidDestroy

File: PIPokes.h
Line: 1100



Copyright 2020 Adobe Systems Incorporated and its licensors. All rights reserved. Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. This product contains either BSAFE and/or TIPEM software by RSA Security, Inc. Portions utilize Microsoft Windows Media Technologies. Copyright © 2006 Microsoft Corporation. All Rights Reserved. Notices, terms and conditions pertaining to other third party software are located at http://www.adobe.com/go/thirdparty/ and incorporated herein by reference.
Tue Jun 23 2020, 12:30 AM GMT+05:30