PD_Layer.PDBookmark (Acrobat)

	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
	`PDBookmarkFlags`

	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: All

Platform availability: All

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.

File: PDExpT.h

Line: 1084

Enumeration Detail

PDBookmarkFlags

Product availability: All

Platform availability: All

Syntax

enum PDBookmarkFlags {

  kPDBookmarkFontNormal = 0x00,


 


  kPDBookmarkFontItalic = 0x01,


 


  kPDBookmarkFontBold = 0x02,


 


  kPDBookmarkFontBoldItalic = 0x03

}

File: PDExpT.h

Line: 1090

Method Detail

PDBookmarkAddChild

()

Product availability: Acrobat, 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.

Notifications

PDBookmarkDidChangePosition

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 909

PDBookmarkAddNewChild

()

Product availability: Acrobat, 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.

Notifications

PDBookmarkDidChangePosition
PDBookmarkWasCreated

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 773

PDBookmarkAddNewChildASText

()

Product availability: All

Platform availability: All

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.

Notifications

PDBookmarkDidChangePosition
PDBookmarkWasCreated

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h

Line: 11486

PDBookmarkAddNewSibling

()

Product availability: Acrobat, 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.

Notifications

PDBookmarkDidChangePosition
PDBookmarkWasCreated

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 752

PDBookmarkAddNewSiblingASText

()

Product availability: All

Platform availability: All

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.

Notifications

PDBookmarkDidChangePosition
PDBookmarkWasCreated

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h

Line: 11460

PDBookmarkAddNext

()

Product availability: Acrobat, 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.

Notifications

PDBookmarkDidChangePosition

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 889

PDBookmarkAddPrev

()

Product availability: Acrobat, 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.

Notifications

PDBookmarkDidChangePosition

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 871

PDBookmarkAddSubtree

()

Product availability: Acrobat, 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.

Notifications

PDBookmarkWillChange
PDBookmarkDidChange
PDBookmarkDidChangePosition

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 797

PDBookmarkAddSubtreeASText

()

Product availability: All

Platform availability: All

Syntax





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

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.

Notifications

PDBookmarkWillChange
PDBookmarkDidChange
PDBookmarkDidChangePosition

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h

Line: 11515

PDBookmarkDestroy

()

Product availability: Acrobat, 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.

Notifications

PDBookmarkWillDestroy
PDBookmarkDidDestroy

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 812

PDBookmarkDidChange

()

Product availability: All

Platform availability: All

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()`.

Notifications

PDBookmarkWillChange
PDBookmarkDidChangePosition

File: PIPokes.h

Line: 1089

PDBookmarkDidChangeOpenState

()

Product availability: All

Platform availability: All

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: All

Platform availability: All

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()`.

Notifications

PDBookmarkWillChange
PDBookmarkDidChange

File: PIPokes.h

Line: 1036

PDBookmarkDidDestroy

()

Product availability: All

Platform availability: All

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: All

Platform availability: All

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: All

Platform availability: All

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: All

Platform availability: All

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: All

Platform availability: All

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.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 1116

PDBookmarkGetByTitle

()

Product availability: All

Platform availability: All

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

File: PDProcs.h

Line: 842

PDBookmarkGetByTitleASText

()

Product availability: All

Platform availability: All

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: 11538

PDBookmarkGetColor

()

Product availability: All

Platform availability: All

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: 7939

PDBookmarkGetCosObj

()

Product availability: All

Platform availability: All

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: All

Platform availability: All

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).

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 853

PDBookmarkGetFirstChild

()

Product availability: All

Platform availability: All

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.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 959

PDBookmarkGetFlags

()

Product availability: All

Platform availability: All

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: 7965

PDBookmarkGetIndent

()

Product availability: All

Platform availability: All

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: All

Platform availability: All

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.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 973

PDBookmarkGetNext

()

Product availability: All

Platform availability: All

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).

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 987

PDBookmarkGetParent

()

Product availability: All

Platform availability: All

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.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 944

PDBookmarkGetPrev

()

Product availability: All

Platform availability: All

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).

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 1002

PDBookmarkGetTitle

()

Product availability: All

Platform availability: All

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.

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h

Line: 1044

PDBookmarkGetTitleASText

()

Product availability: All

Platform availability: All

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.

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h

Line: 11417

PDBookmarkHasChildren

()

Product availability: All

Platform availability: All

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: All

Platform availability: All

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: All

Platform availability: All

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: Acrobat, 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: 7800

PDBookmarkSetAction

()

Product availability: Acrobat, 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: Acrobat, 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: 7952

PDBookmarkSetFlags

()

Product availability: Acrobat, 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: 7980

PDBookmarkSetOpen

()

Product availability: All

Platform availability: All

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: Acrobat, 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

File: PDProcs.h

Line: 1071

PDBookmarkSetTitleASText

()

Product availability: All

Platform availability: All

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.

Exceptions

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

Notifications

PDBookmarkWillChange
PDBookmarkDidChange

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h

Line: 11435

PDBookmarkUnlink

()

Product availability: Acrobat, 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: All

Platform availability: All

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()`.

Notifications

PDBookmarkDidDestroy
PDBookmarkWillDestroy

File: PIPokes.h

Line: 1019

PDBookmarkWillChange

()

Product availability: All

Platform availability: All

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().

Notifications

PDBookmarkDidChange
PDBookmarkDidChangePosition

File: PIPokes.h

Line: 1066

PDBookmarkWillChangeOpenState

()

Product availability: All

Platform availability: All

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: All

Platform availability: All

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

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
PDBookmark	Typedefs \| Enumerations \| Methods

	kPDBookmarkFontNormal = 0x00,

	kPDBookmarkFontItalic = 0x01,

	kPDBookmarkFontBold = 0x02,

	kPDBookmarkFontBoldItalic = 0x03

Layer	PD_Layer
Object	PDBookmark