Foxit PDF SDK

Instance Methods | List of all members
FSPDFNameTree Class Reference
Inheritance diagram for FSPDFNameTree:

## Instance Methods
(BOOL) | - add:pdf_object:
| Add a new key name with a PDF object as its value. More...
(int) | - getCount
| Get the count of elements in current name tree. More...
(NSString *) | - getName:
| Get a key name in the name tree, by index. More...
(FSPDFObject *) | - getObj:
| Get the value (as PDF object) of a specified key name. More...
(FSPDFNameTreeType) | - getType
| Get the type of current name tree. More...
(BOOL) | - hasName:
| Check if the specified key name exists in current name tree. More...
(id) | - init
| Constructor.
(id) | - initWithDocument:type:
| Constructor, with parameters. More...
(id) | - initWithOther:
| Constructor, with another PDF name tree object. More...
(BOOL) | - isEmpty
| Check whether current object is empty or not. More...
(BOOL) | - removeAllObjs
| Remove all key names from current name tree, along with theirs value (as PDF object). More...
(BOOL) | - removeObj:
| Remove a key name from current name tree, along with its value (as PDF object). More...
(BOOL) | - rename:new_name:
| Rename an existing key name to a new key name. More...
(BOOL) | - setObj:pdf_object:
| Set the value (as PDF object) of a specified key name. More...

## Detailed Description

Name tree is a kind of common data structure in PDF. Name tree serves a similar purpose to PDF dictionary

- associating keys and values - but by different means: in the name tree, a key name is treated as an alias of its value object. That means, the value object can be referred to by the key name instead of by reference object.
  Name tree has following characteristics:
  - key names in a name tree are ordered and each key name in the same name tree is unique;
  - values associated with the key names may be objects of any type, depending on the purpose of the name tree;
  - name tree can represent an arbitrarily large collection of key-value pairs, which can be looked up efficiently without requiring the entire data structure to be read from the PDF file.
  Class FSPDFNameTree is used to be associated with an existing name tree with specified type or create one. It offers functions to get key-value pairs in the name tree, and set/add/remove any key-value pair. Currently, class FSPDFNameTree can be associated with following name trees defined in PDF document:
  - Destinations name tree (with type FSPDFNameTreeDests), which maps name strings to destinations. Values in this name tree should be a destination array (or a reference object to destination array).
  - JavaScript name tree (with type FSPDFNameTreeJavaScript), which maps name strings to document-level JavaScript actions. Values in this name tree should be a javaScript action dictionary (or a reference object to javaScript action dictionary).
  - EmbeddedFiles name tree, with type FSPDFNameTreeEmbeddedFiles, which maps name strings to file specifications for embedded file streams. Values in this name tree should be a file specification dictionary (or a reference object to file specification dictionary), which contains an embedded file stream.
  - Pages name tree, with type FSPDFNameTreePages, which maps name strings to pages. Values in this name tree should be a reference object to a page dictionary.
  - Templates name tree, with type FSPDFNameTreeTemplates, which maps name strings to hidden pages. Values in this name tree should be a reference object to a hidden page dictionary. Please use function FSPDFDoc::hidePageTemplate: to hide pages.
  For convenient use about embedded files (known as attachments as well) in a PDF document, please refer to class FSAttachments.

See also
  FSAttachments

## Method Documentation

## ◆ add:pdf_object:()

- (BOOL) add: |  | (NSString *) | name
pdf_object: |  | (FSPDFObject*) | pdf_object

Add a new key name with a PDF object as its value.

All PDF objects in the name tree are ordered by their names. When a new PDF object is added, Foxit PDF SDK will find a suitable place in the name tree to add it. After adding successfully, the indexes of some old keys may be changed.

Parameters

  [in] | name | String for a new key name. This should not be an empty string. This new name should not have existed in current name tree.
  [in] | pdf_object | A PDF object, to be set with the new name. The type of this PDF object should match current name tree; otherwise, the input PDF object is invalid. Please refer to comment of class FSPDFNameTree for more details. User should not release this PDF object after this function succeeds.

Returns
  YES means success, while NO means failure.

## ◆ getCount()

- (int) getCount |  |  |

Get the count of elements in current name tree.

Returns
  The element count.

## ◆ getName:()

- (NSString *) getName: |  | (int) | index |

Get a key name in the name tree, by index.

Parameters

  [in] | index | Index of the key name to be retrieved. Valid range: from 0 to (count-1). count is returned by function FSPDFNameTree::getCount.

Returns
  A string that represents the key name.

## ◆ getObj:()

- (FSPDFObject *) getObj: |  | (NSString *) | name |

Get the value (as PDF object) of a specified key name.

Parameters

  [in] | name | String for a key name. It should not be an empty string.

Returns
  A FSPDFObject object. The type of returned PDF object depends on the purpose of current name tree. Please refer to comment of class FSPDFNameTree for more details. If not found, this function will return nil.

## ◆ getType()

- (FSPDFNameTreeType) getType |  |  |

Get the type of current name tree.

Returns
  Type of current name tree. Please refer to values starting from FSPDFNameTreeDests and this would be one of these values.

## ◆ hasName:()

- (BOOL) hasName: |  | (NSString *) | name |

Check if the specified key name exists in current name tree.

Parameters

  [in] | name | A string that represents the key name to be checked. It should not be an empty string.

Returns
  YES means the specified name exists in current name tree, and NO means the specified name does not exist in current name tree.

## ◆ initWithDocument:type:()

- (id) initWithDocument: |  | (FSPDFDoc*) | document
type: |  | (FSPDFNameTreeType) | type

Constructor, with parameters.

If there exists name tree with specified type in the PDF document, this function is just to construct a PDF name tree object to be associated with the name tree. If there is no such name tree in PDF document, the constructed PDF name tree object can be used to create such name tree in PDF document and add items to the name tree.

Parameters

  [in] | document | A valid PDF document object.
  [in] | type | The type of the name tree. Please refer to values starting from FSPDFNameTreeDests and this should be one of these values.

## ◆ initWithOther:()

- (id) initWithOther: |  | (FSPDFNameTree*) | other |

Constructor, with another PDF name tree object.

Parameters

  [in] | other | Another PDF name tree object.

## ◆ isEmpty()

- (BOOL) isEmpty |  |  |

Check whether current object is empty or not.

When the current object is empty, that means current object is useless.

Returns
  YES means current object is empty, while NO means not.

## ◆ removeAllObjs()

- (BOOL) removeAllObjs |  |  |

Remove all key names from current name tree, along with theirs value (as PDF object).

Returns
  YES means success, while NO means failure.

## ◆ removeObj:()

- (BOOL) removeObj: |  | (NSString *) | name |

Remove a key name from current name tree, along with its value (as PDF object).

If the input name does not exist in current name tree, this function will return YES directly.

Parameters

  [in] | name | String for a key name to be removed. This should not be an empty string.

Returns
  YES means success, while NO means failure.

## ◆ rename:new_name:()

- (BOOL) rename: |  | (NSString *) | old_name
new_name: |  | (NSString *) | new_name

Rename an existing key name to a new key name.

Parameters

  [in] | old_name | String for an old key name which is to be renamed. This should not be an empty string. This name should have existed in current name tree.
  [in] | new_name | String for a new key name. This should not be an empty string. This new name should not have existed in current name tree.

Returns
  YES means success, while NO means failure.

## ◆ setObj:pdf_object:()

- (BOOL) setObj: |  | (NSString *) | name
pdf_object: |  | (FSPDFObject*) | pdf_object

Set the value (as PDF object) of a specified key name.

Parameters

  [in] | name | String for a key name. It should not be an empty string. This name should have existed in current name tree.
  [in] | pdf_object | A PDF object to be set as the name's value. It should not be nil. The type of this PDF object should match current name tree; otherwise, the input PDF object is invalid. Please refer to comment of class FSPDFNameTree for more details. User should not release this PDF object after this function succeeds.

Returns
  YES means success, while NO means failure.