Guides

Outlines

An outline is a structured navigation tool in a PDF document. It is typically displayed in the sidebar or panel of the reader. It can be generated automatically from headings and chapter information, or edited manually to help locate and browse different sections of the document.

Get the Outlines

Each heading or subheading in a PDF document can be represented as a node in the outline tree. The main heading usually acts as the root node, while subheadings become child nodes, forming a tree structure.

The following example recursively retrieves all nodes in the PDF outline tree:

java

public ArrayList<CPDFOutline> getAllOutlines() {
    ArrayList<CPDFOutline> outlineList = new ArrayList<>();
    CPDFOutline pdfOutlineRoot = document.getOutlineRoot();
    if (pdfOutlineRoot == null) {
        return outlineList;
    }
    collectChildOutlines(pdfOutlineRoot, outlineList);
    return outlineList;
}

private void collectChildOutlines(CPDFOutline parent, ArrayList<CPDFOutline> result) {
    CPDFOutline[] childOutlines = parent.getChildList();
    for (CPDFOutline childOutline : childOutlines) {
        result.add(childOutline);
        collectChildOutlines(childOutline, result);
    }
}

kotlin

fun getAllOutlines(): MutableList<CPDFOutline> {
    val pdfOutlineRoot: CPDFOutline = document.getOutlineRoot() ?: return mutableListOf()
    val outlineList = mutableListOf<CPDFOutline>()
    collectChildOutlines(pdfOutlineRoot, outlineList)
    return outlineList
}

private fun collectChildOutlines(parent: CPDFOutline, result: MutableList<CPDFOutline>) {
    parent.childList.forEach { childOutline ->
        result.add(childOutline)
        collectChildOutlines(childOutline, result)
    }
}

Add a New Outline

The following are the steps for adding a new outline:

1. Get the target parent outline. If the document does not have a root outline, create one first.
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:

java

// Get the root outline; create one if it does not exist.
CPDFOutline pdfOutlineRoot = document.getOutlineRoot();
if (pdfOutlineRoot == null) {
    pdfOutlineRoot = document.newOutlineRoot();
}
CPDFOutline insertOutline = pdfOutlineRoot.insertChildAtIndex(0);
// Set properties
insertOutline.setTitle("New outline");
// Add outline action; in this case, it is to navigate to the first page.
int pageIndex = 0;
CPDFDestination destination = new CPDFDestination(pageIndex, 0F, 0, 1F);
insertOutline.setDestination(destination);

kotlin

// Get the root outline; create one if it does not exist.
val pdfOutlineRoot: CPDFOutline = document.getOutlineRoot() ?: document.newOutlineRoot()
pdfOutlineRoot.insertChildAtIndex(0).apply { 
  // Set properties.
  title = "insert0"
  // Add outline action; in this case, it is to navigate to the first page.
  destination = CPDFDestination(0, 0F, 0F, 1F)
}

Adjust the Order of the Outlines

To reorder outlines, first determine the outline node to move, the target parent node, and the insertion index.

// Target parent node
CPDFOutline newParentOutline;

// Move the current outline node to the target parent node at insertIndex
outline.moveTo(newParentOutline, insertIndex);

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 call the delete method:

outline.removeFormParent();