Outlines Reference

See also

Working with Outlines

class pdfnaut.objects.outlines.OutlineItem

Bases: PdfDictionary

An outline item within the outline tree.

See ISO 32000-2:2020 “Table 151 - Entries in an outline item dictionary” for details.

__init__(text: str, flags: OutlineItemFlags = OutlineItemFlags.NULL, destination: PdfName | PdfHexString | bytes | Destination | None = None, action: Action | None = None, color: list[float] | None = None, *, pdf: PdfParser | None = None, indirect_ref: PdfReference | None = None) → None

property action: Action | None

The action that shall be triggered when the item is activated.

property children: OutlineList

The immediate children of the outline item.

close() → None

If the item has children, closes the outline item and hides the immediate children.

color: list[float]

The color that shall be used for the outline item text, as an array of RGB color components in the range 0 to 1.

property destination: PdfName | PdfHexString | bytes | Destination | None

The destination that shall be displayed when the item is activated, either a named destination (a name or byte string) or an explicit destination (a Destination object).

property first: OutlineItem | None

The first child item of the outline if any.

flags: OutlineItemFlags

A set of bit flags describing characteristics of the outline item text.

property last: OutlineItem | None

The last child item of the outline if any.

property next: OutlineItem | None

The next item at the current outline level if any.

open() → None

If the item has children, opens the outline item and displays the immediate children (and its descendants if they are also visible).

property parent: OutlineItem | OutlineTree

The parent outline item or tree containing this outline.

property previous: OutlineItem | None

The previous item at the current outline level if any.

text: str

The display text for this outline item.

property visible_items: int

• If the outline item is open, the number of visible descendent outline items.

• If the outline item is closed, a negative number representing the number of descendants that would be visible if the item were opened.

• If the outline item has no children, zero.

class pdfnaut.objects.outlines.OutlineItemFlags

Bases: IntFlag

Flags specifying style characteristics for an outline item. See “Table 152 - Outline item flags” for details.

BOLD = 2

Display the outline item text in bold.

ITALIC = 1

Display the outline item text in italic.

NULL = 0

No flags

__new__(value)

class pdfnaut.objects.outlines.OutlineList

Bases: MutableSequence[OutlineItem]

The outline list representing the children of an outline tree or item.

Warning

This class is not designed to be constructed by a user. Using the outline list should be done via OutlineTree and OutlineItem.

__init__(pdf: PdfParser, parent: OutlineItem | OutlineTree) → None

append(value: OutlineItem) → None

Appends an outline item value to the immediate children of the list.

clear() → None

Removes all children in the outline item.

count(value: Any) → int

Returns the amount of times outline item value appears in the page list.

extend(values: Iterable[OutlineItem]) → None

Appends a list of outline items values to the end of the outline list.

index(value: Any, start: int = 0, stop: int = sys.maxsize) → int

Returns the index at which outline item value was first found in the range of start included to stop excluded.

insert(index: int, value: OutlineItem) → None

S.insert(index, value) – insert value before index

pop(index: int = -1) → OutlineItem

Removes the outline item at index from the immediate children of this outline list.

Raises:

IndexError – The outline list is empty or the item is not in the list.

Returns:

The outline item that was popped.

Return type:

OutlineItem

remove(value: OutlineItem) → None

Removes the first occurrence of outline item value in the immediate children of this tree.

Raises:

IndexError – The outline list is empty or the item is not in the list.

reverse() → None

S.reverse() – reverse IN PLACE

class pdfnaut.objects.outlines.OutlineTree

Bases: PdfDictionary

The document outline tree containing a hierarchy of outline items that allow navigating throughout the document.

See ISO 32000-2:2020 § 12.3.3 “Document outline” for details.

Warning

This class is not designed to be constructed by a user. To add an outline tree to a document, PdfDocument.new_outline() should be used.

__init__(pdf: PdfParser, tree: PdfDictionary, tree_ref: PdfReference) → None

property children: OutlineList

The immediate children of the outline tree.

close() → None

If the item has children, closes all outline items within the tree.

property first: OutlineItem | None

The first outline item in the tree.

property last: OutlineItem | None

The last outline item in the tree.

open() → None

If the item has children, opens all outline items within the tree.

property visible_items: int

The total number of visible outline items at all levels of the tree.

pdfnaut.objects.outlines.flatten_outlines(item: OutlineItem | OutlineTree) → Generator[OutlineItem, None, None]

Yields the immediate children of the outline item.

pdfnaut.objects.outlines.get_count(item: OutlineTree | OutlineItem) → int

Calculates the count of visible items within an outline item or tree.

pdfnaut.objects.outlines.is_outline_tree(item: PdfDictionary) → bool

Reports whether a dictionary item is an outline tree.

pdfnaut.objects.outlines.update_ancestor_count(item: OutlineTree | OutlineItem) → None

Recalculates the visible item count for the outline item, reflecting this count in the ancestors.