Outlines ​

The outline is a structured navigation tool in PDF documents, typically displayed in the sidebar or panel of a document reader. It is often automatically generated based on the document's headings and chapter information, but can also be manually edited and adjusted.

The outline provides a hierarchical structure of the document, enabling users to locate and navigate content more easily. Additionally, users can use the outline to quickly navigate to different sections of the document.

Display the Outlines ​

Each heading or subheading in a PDF document is represented as a node in the outline tree, with branches connecting the nodes. The main title serves as the root node, and subheadings act as branches stemming from the root, forming a tree-like structure.

The outline is formed by recursively nesting nodes and subnodes, presenting the organizational framework of the document in a hierarchical manner. Nodes typically represent major sections, while subnodes represent subsections or chapters.

This example shows how to display the outline of a PDF recursively:

// Print document outline information.
func printOutline(document: CPDFDocument) {
    // Retrieve the root file from the PDF document.
    if let outline = document.outlineRoot() {
        // Get subdirectories from the root directory.
        loadOutline(outline: outline, level: 0)
    }
}

// Retrieve subdirectories from the root directory.
func loadOutline(outline: CPDFOutline, level: Int) {
    for i in 0..<outline.numberOfChildren {
        if let data = outline.child(at: i) {
            if let destination = data.destination {
                
            } else {
                if let action = data.action as? CPDFGoToAction {
                    if let destination = action.destination() {
                        
                    }
                }
            }

            loadOutline(outline: data, level: level + 1)
        }
    }
}

// Print document outline information.
- (void)printOutline:(CPDFDocument *)document {
    // Retrieve the root file from the PDF document.
    CPDFOutline *outline = [document outlineRoot];
    
    // Get subdirectories from the root directory.
    [self loadOutline:outline level:0];
}

// Retrieve subdirectories from the root directory.
- (void)loadOutline:(CPDFOutline *)outline level:(NSInteger)level {
    
    for (int i=0; i<[outline numberOfChildren]; i++) {
        CPDFOutline *data = [outline childAtIndex:i];
        CPDFDestination *destination = [data destination];
        if (!destination) {
            CPDFAction *action = [data action];
            if (action && [action isKindOfClass:[CPDFGoToAction class]]) {
                destination = [(CPDFGoToAction *)action destination];
            }

        [self loadOutline:data level:level+1];
    }
}

Add a New Outline ​

The following are the steps for adding a new outline:

1. Locate the parent outline where the new outline needs to be added.
2. Create a new outline.
3. Add actions to the outline, such as jumping to a page.
4. Set properties.

This example shows how to add a new outline:

// Identify the parent outline where the new outline entry needs to be added.
if let outlineRoot = document?.outlineRoot() {
    // Create the outline entry to be added.
    if let outlinePage = outlineRoot.insertChild(at: 0) {
        // Add outline action, in this case, navigate to the first page.
        if let destination = CPDFDestination(document: document, pageIndex: 0, at: CGPoint(x: 100, y: 100), zoom: 0) {
            let gotoAction = CPDFGoToAction(destination: destination)
            outlinePage.action = gotoAction
        }
        
        // Set the attributes.
        outlinePage.label = "1. page1"
    }
}

 // Identify the parent outline where the new outline entry needs to be added.
 CPDFOutline *outline = [document outlineRoot];
 // Create the outline entry to be added.
 CPDFOutline *outlinePage = [outline insertChildAtIndex:0];
 // Add outline action, in this case, navigate to the first page.
CPDFDestination *destination = [[CPDFDestination alloc] initWithDocument:document pageIndex:0 atPoint:CGPointMake(100, 100) zoom:0];
CPDFGoToAction *gotoAction = [[CPDFGoToAction alloc] initWithDestination:destination];
outlinePage.action = gotoAction;
 // Set the attributes.
outlinePage1.label = @"1. page1";

Adjust the Order of the Outlines ​

Adjust the outline order using the function CPDFOutline::insertChild:atIndex:. When moving an item in the outline hierarchy, ensure to retain the item and first call CPDFOutline::removeFromParent.

Delete the Outline ​

Delete the target outline, after deletion, the child outlines of the target outline will also be removed.

This example shows how to delete the outlines:

var data = outline.child(at: i)
data?.removeFromParent()

CPDFOutline *data = [outline childAtIndex:i];
[data removeFromParent]