PD_Layer.PDNameTree (Acrobat)

	Typedef
	PDNameTree The dictionary used to store all of the Named Destinations in a PDF file. A name tree is used to map Cos strings to Cos objects just as a Cos dictionary is used to map Cos names to Cos objects. However, a name tree can have many more entries than a Cos dictionary can. You create a PDNameTree and locate it where you think is appropriate (perhaps under a page, but most often right under the catalog). Name trees use Cos-style strings (not NULL-terminated C strings), which may use Unicode encoding, and these may contain bytes with zeroes in them (high bytes of ASCII characters).

	Method
	void PDNameTreeEnum(PDNameTree theTree, CosObjEnumProc proc, void* clientData) Enumerates the entries in the tree.
	ASBool PDNameTreeEqual(PDNameTree tree1, PDNameTree tree2) Compares two name trees to determine if they are the same object.
	PDNameTree PDNameTreeFromCosObj(CosObj obj) Creates a type cast of the CosObj to a name tree. This does not copy the object.
	ASBool PDNameTreeGet(PDNameTree theTree, const char* name, ASInt32 nameLen, CosObj* value) Retrieves an object from the name tree.
	CosObj PDNameTreeGetCosObj(PDNameTree theTree) Creates a type cast of the name tree to a CosObj. This does not copy the object.
	ASBool PDNameTreeIsValid(PDNameTree theTree) Validates whether a PDNameTree is a CosDict Cos object.
	CosObj PDNameTreeLookup(CosObj nameTree, char* string, ASInt32 stringLen) Given a name tree (such as the Dests tree in the Names dictionary) and a string, find the CosObj in the tree that matches the string.
	void PDNameTreeNameAdded(PDNameTree NameTree, CosObj Key, CosObj Value, void* clientData) An entry was added to a name tree.
	void PDNameTreeNameRemoved(PDNameTree NameTree, CosObj Key, void* clientData) An entry was removed from a name tree.
	void PDNameTreeNameWillRemove(PDNameTree tree, const char* key, ASInt32 keyLen, void* clientData) An entry will be removed from the PDNameTree.
	PDNameTree PDNameTreeNew(PDDoc pdDoc) Creates a new name tree in the document.
	void PDNameTreeNotifyNameAdded(PDNameTree theTree, CosObj key, CosObj value) Sends a PDNameTreeNameAdded() notification.
	void PDNameTreeNotifyNameRemoved(PDNameTree theTree, CosObj removedName) Sends a PDNameTreeNameRemoved() notification.
	void PDNameTreePut(PDNameTree theTree, CosObj key, CosObj value) Puts a new entry in the name tree. If an entry with this name is already in the tree, it is replaced.
	void PDNameTreeRemove(PDNameTree theTree, const char* key, ASInt32 keyLen) Removes the specified object from the tree. It does nothing if no object with that name exists.

Typedefs Detail

PDNameTree

Product availability: All

Platform availability: All

Syntax

typedef OPAQUE_64_BITS PDNameTree;

The dictionary used to store all of the Named Destinations in a PDF file. A name tree is used to map Cos strings to Cos objects just as a Cos dictionary is used to map Cos names to Cos objects. However, a name tree can have many more entries than a Cos dictionary can. You create a PDNameTree and locate it where you think is appropriate (perhaps under a page, but most often right under the catalog). Name trees use Cos-style strings (not NULL-terminated C strings), which may use Unicode encoding, and these may contain bytes with zeroes in them (high bytes of ASCII characters).

File: PDExpT.h

Line: 5433

Method Detail

PDNameTreeEnum

()

Product availability: All

Platform availability: All

Syntax





void PDNameTreeEnum(PDNameTree theTree, CosObjEnumProc proc, void* clientData)

Enumerates the entries in the tree.

Parameters

	`theTree` —	IN/OUT A name tree.

	`proc` —	IN/OUT A procedure to call once for each name/object pair in `theTree`. The obj/value pair in `proc` correspond to the Cos string and CosObj values of each leaf in the tree.

	`clientData` —	IN/OUT Data used by the enumeration procedure. `clientData` is passed to the enumeration procedure proc each time an entry is encountered.

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6898

PDNameTreeEqual

()

Product availability: All

Platform availability: All

Syntax





ASBool PDNameTreeEqual(PDNameTree tree1, PDNameTree tree2)

Compares two name trees to determine if they are the same object.

Parameters

	`tree1` —	A name tree.

	`tree2` —	Another name tree.

Returns

true if the two name trees are equivalent, false otherwise.

See Also

PDNameTreeIsValid

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6828

PDNameTreeFromCosObj

()

Product availability: All

Platform availability: All

Syntax





PDNameTree PDNameTreeFromCosObj(CosObj obj)

Creates a type cast of the CosObj to a name tree. This does not copy the object.

Parameters

obj —

IN/OUT The CosObj for which a PDNameTree representation is desired.

Returns

A PDNameTree representation of obj.

See Also

PDNameTreeNew
PDNameTreeGetCosObj

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6790

PDNameTreeGet

()

Product availability: All

Platform availability: All

Syntax





ASBool PDNameTreeGet(PDNameTree theTree, const char* name, ASInt32 nameLen, CosObj* value)

Retrieves an object from the name tree.

Parameters

	`theTree` —	The PDNameTree from which an object is retrieved.

	`name` —	The name of the object within `theTree` to get. This is a Cos-style string, not a C string.

	`nameLen` —	The length of `name`.

	`value` —	(Filled by the method) The Cos object corresponding to `name` within `theTree`.

Returns

true if the object was retrieved, false if no object with this name exists.

See Also

PDNameTreePut
PDNameTreeRemove

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6863

PDNameTreeGetCosObj

()

Product availability: All

Platform availability: All

Syntax





CosObj PDNameTreeGetCosObj(PDNameTree theTree)

Creates a type cast of the name tree to a CosObj. This does not copy the object.

Parameters

theTree —

IN/OUT The PDNameTree for which a CosObj representation is desired.

Returns

A CosObj representation of theTree.

See Also

PDNameTreeNew
PDNameTreeFromCosObj

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6803

PDNameTreeIsValid

()

Product availability: All

Platform availability: All

Syntax





ASBool PDNameTreeIsValid(PDNameTree theTree)

Validates whether a PDNameTree is a CosDict Cos object.

Parameters

theTree —

The PDNameTree whose validity is desired.

Returns

true if the name tree is a CosDict, false otherwise.

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6816

PDNameTreeLookup

()

Product availability: All

Platform availability: All

Syntax





CosObj PDNameTreeLookup(CosObj nameTree, char* string, ASInt32 stringLen)

Given a name tree (such as the Dests tree in the Names dictionary) and a string, find the CosObj in the tree that matches the string.

See Section 3.8.5 in the PDF Reference for more information on name trees.

Parameters

	`nameTree` —	The name tree in which to search.

	`string` —	The name to search for. The name tree uses Cos-style strings, which may use Unicode encoding, and these may contain bytes with zeroes in them (high bytes of ASCII characters). Note that `name` is not a C-style string. Cos string objects can contain `NULL` chars. Standard C string-handling functions may not work as expected.

	`stringLen` —	The length of `name` in bytes.

Returns

The Cos object associated with the specified name, which is the array element following the name.

See Also

PDNameTreeGet
PDNameTreePut

Since

PI_PDMODEL_VERSION >= 0x00020002

File: PDProcs.h

Line: 6117

PDNameTreeNameAdded

()

Product availability: All

Platform availability: All

Syntax





void PDNameTreeNameAdded(PDNameTree NameTree, CosObj Key, CosObj Value, void* clientData)

An entry was added to a name tree.

Parameters

	`NameTree` —	The name tree to which an entry was added.

	`Key` —	The Cos object of the key for the entry. This object is a Cos integer.

	`Value` —	The Cos object for the value associated with key.

	`clientData` —	A pointer to a block of user-supplied data that was passed in by the calling application when this notification was registered for using `AVAppRegisterNotification()`.

See Also

PDNameTreeNotifyNameAdded

Notifications

PDNameTreeNameRemoved

File: PIPokes.h

Line: 1684

PDNameTreeNameRemoved

()

Product availability: All

Platform availability: All

Syntax





void PDNameTreeNameRemoved(PDNameTree NameTree, CosObj Key, void* clientData)

An entry was removed from a name tree.

Parameters

	`NameTree` —	The name tree from which an entry was removed.

	`Key` —	The Cos object of the key for the entry. This object is a Cos integer.

	`clientData` —	A pointer to a block of user-supplied data that was passed in by the calling application when this notification was registered for using `AVAppRegisterNotification()`.

See Also

PDNameTreeNotifyNameRemoved

Notifications

PDNameTreeNameAdded

File: PIPokes.h

Line: 1698

PDNameTreeNameWillRemove

()

Product availability: All

Platform availability: All

Syntax





void PDNameTreeNameWillRemove(PDNameTree tree, const char* key, ASInt32 keyLen, void* clientData)

An entry will be removed from the PDNameTree.

Parameters

	`tree`

	`key`

	`keyLen`

	`clientData`

File: PIPokes.h

Line: 2587

PDNameTreeNew

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





PDNameTree PDNameTreeNew(PDDoc pdDoc)

Creates a new name tree in the document.

Parameters

pdDoc —

The document for which a new name tree is desired.

Returns

The newly created name tree or a NULL CosObj if Acrobat is unable to create a PDNameTree for the document specified by pdDoc.

PDNameTreeIsValid() should be called to determine if the name tree returned by PDNameTreeNew() is usable.

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6777

PDNameTreeNotifyNameAdded

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDNameTreeNotifyNameAdded(PDNameTree theTree, CosObj key, CosObj value)

Sends a PDNameTreeNameAdded() notification.

Parameters

	`theTree` —	The PDNameTree to which a name had been added.

	`key` —	The name of the object within `theTree` that was added. This is a Cos string, not a C string.

	`value` —	(Filled by the method) The Cos object corresponding to the object name that was added to `theTree`.

See Also

PDNameTreeNotifyNameRemoved

Notifications

PDNameTreeNameAdded

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h

Line: 7828

PDNameTreeNotifyNameRemoved

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDNameTreeNotifyNameRemoved(PDNameTree theTree, CosObj removedName)

Sends a PDNameTreeNameRemoved() notification.

Parameters

	`theTree` —	The PDNameTree from which the name had been removed.

	`removedName` —	The name within `theTree` that was removed.

See Also

PDNameTreeNotifyNameAdded

Notifications

PDNameTreeNameRemoved

Since

PI_PDMODEL_VERSION >= 0x00050000

File: PDProcs.h

Line: 7839

PDNameTreePut

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDNameTreePut(PDNameTree theTree, CosObj key, CosObj value)

Puts a new entry in the name tree. If an entry with this name is already in the tree, it is replaced.

Parameters

	`theTree` —	IN/OUT The name tree for which a new entry is added.

	`key` —	IN/OUT The name of the object to put in the tree. This is a Cos-style string, not a C string. This allows the use of an existing indirect object for the key rather than forcing the creation of a new object.

	`value` —	IN/OUT The Cos object to be associated with `key`.

See Also

PDNameTreeGet

Notifications

PDNameTreeNameAdded

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6846

PDNameTreeRemove

()

Product availability: Acrobat, PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDNameTreeRemove(PDNameTree theTree, const char* key, ASInt32 keyLen)

Removes the specified object from the tree. It does nothing if no object with that name exists.

Parameters

	`theTree` —	IN/OUT The name tree from which an entry is removed.

	`key` —	IN/OUT The name of the entry to remove. This is a Cos- style string, not a C string.

	`keyLen` —	IN/OUT The length of `key` in bytes.

See Also

PDNameTreeGet
PDNameTreePut

Notifications

PDNameTreeNameRemoved

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h

Line: 6879

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

Layer	PD_Layer
Object	PDNameTree