---

PDFOutline Class Reference

Overview

A PDFOutline object is an element in a tree-structured hierarchy that can represent the structure of a PDF document.

An outline is an optional component of a PDF document, useful for viewing the structure of the document and for navigating within it.

Outlines are created by the document’s author. If you represent a PDF document outline using outline objects, the root of the hierarchy is obtained from the PDF document itself. This root outline is not visible and serves merely as a container for the visible outlines.

Tasks

Initializing an Outline

• – init
• – initWithDocument:

Getting Information About an Outline

• – document
• – numberOfChildren
• – parent
• – childAtIndex:
• – index

Managing Outline Labels

• – label
• – setLabel:

Managing Actions and Destinations

• – destination
• – action
• – setAction:
• – setDestination:

Changing an Outline Hierarchy

• – insertChild:atIndex:
• – removeFromParent

Managing the Disclosure of an Outline Object

• – isOpen
• – setIsOpen:

Instance Methods

action

Returns the action performed when users click the outline.

- (PDFAction *)action

Discussion

The root outline serves only as a container for the outlines it owns; it does not have an action. Note that a PDFOutline object can have either an action or a destination, not both.

If the PDFOutline object has a destination, instead of an action, action returns a PDFActionGoTo object (this is equivalent to calling destination on the PDFOutline object). For other action types, action returns the appropriate PDF Kit action type object, such as PDFActionURL.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setAction:

Declared In

PDFOutline.h

childAtIndex:

Returns the child outline object at the specified index.

- (PDFOutline *)childAtIndex:(NSUInteger)index

Discussion

The index is zero-based. This method throws an exception if index is out of range.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – index

Declared In

PDFOutline.h

destination

Returns the destination associated with the outline.

- (PDFDestination *)destination

Discussion

The root outline serves only as a container for the outlines it owns; it does not have a destination. Note that a PDFOutline object can have either a destination or an action, not both.

This method may return NULL if the outline has an associated action instead of a destination. Note that if the associated action is a PDFActionGoTo, this method returns the destination from the PDFActionGoTo object. However, it is better to use the action method for this purpose.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setDestination:

Declared In

PDFOutline.h

document

Returns the document with which the outline is associated.

- (PDFDocument *)document

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDFOutline.h

index

Returns the index of the outline.

- (NSUInteger)index

Discussion

The index of the outline object is relative to its siblings and from the perspective of the parent of the outline object. The root outline object, and any outline object without a parent, has an index value of 0.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

PDFOutline.h

init

Initializes a PDFOutline object.

- (id)init

Discussion

If you want the PDFOutline object returned by this method to be the outline root, you must add additional PDFOutline objects to create the outline hierarchy you desire. Then, you must add the root outline object to your PDF document by passing it to the PDFDocument setOutlineRoot: method.

If you want the PDFOutline object returned by this method to be a child of an existing outline, you must use setLabel: to give it a label and give it either a destination or action using setDestination: or setAction:, respectively. In addition, you must add this outline object to the existing PDFOutline object as a new child, using insertChild:atIndex:

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDFOutline.h

initWithDocument:

Initializes an outline with the specified PDF document. (Deprecated. Use the PDFDocument outlineRoot method instead.)

- (id)initWithDocument:(PDFDocument *)document

Discussion

Returns NULL if the document does not contain an outline. Invoking this method is equivalent to sending the outlineRoot message to a PDFDocument object.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

PDFOutline.h

insertChild:atIndex:

Inserts the specified outline object at the specified index.

- (void)insertChild:(PDFOutline *)child atIndex:(NSUInteger)index

Discussion

To build a PDF outline hierarchy, use this method to add child outline objects. Before you call this method on a PDFOutline object that already has a parent, you should retain the object and call removeFromParent on it first.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – childAtIndex:

Declared In

PDFOutline.h

isOpen

Returns a Boolean value that indicates whether the outline object is initially disclosed.

- (BOOL)isOpen

Discussion

Calling isOpen on an outline object that has no children always returns NO. Calling isOpen on the root outline object always returns YES.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setIsOpen:

Declared In

PDFOutline.h

label

Returns the label for the outline.

- (NSString *)label

Discussion

The root outline serves only as a container for the outlines it owns; it does not have a label.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setLabel:

Declared In

PDFOutline.h

numberOfChildren

Returns the number of child outline objects in the outline.

- (NSUInteger)numberOfChildren

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – childAtIndex:

Declared In

PDFOutline.h

parent

Returns the parent outline object of the outline (returns NULL if called on the root outline object).

- (PDFOutline *)parent

Availability

• Available in Mac OS X v10.5 and later

Declared In

PDFOutline.h

removeFromParent

Removes the outline object from its parent (does nothing if outline object is the root outline object).

- (void)removeFromParent

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – parent

Declared In

PDFOutline.h

setAction:

Sets the action associated with the outline.

- (void)setAction:(PDFAction *)action

Discussion

Calling setAction on the root outline object has no effect, because the root outline does not have an action or a destination..

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – action

Declared In

PDFOutline.h

setDestination:

Sets the destination associated with the outline.

- (void)setDestination:(PDFDestination *)destination

Discussion

Calling setDestination on the root outline object has no effect, because the root outline does not have an action or a destination.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – destination

Declared In

PDFOutline.h

setIsOpen:

Sets the initial disclosure state of the outline object.

- (void)setIsOpen:(BOOL)open

Discussion

Calling setIsOpen on an outline object with no children or on the root outline object has no effect.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – isOpen

Declared In

PDFOutline.h

setLabel:

Sets the label for the outline (has no effect on the root outline object).

- (void)setLabel:(NSString *)label

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – label

Declared In

PDFOutline.h

---