pdftools_toolbox.pdf.navigation.outline_item

Classes

OutlineItem(handle)

An outline item represents an entry in the outline tree of the document.

class pdftools_toolbox.pdf.navigation.outline_item.OutlineItem(handle)

Bases: _NativeObject

An outline item represents an entry in the outline tree of the document. It is also known as “Bookmark”.

static create(target_document: Document, title: str, destination: Destination | None) → OutlineItem

Create a new outline item (bookmark).

The returned outline item is not yet part of the outline item tree, but it is associated with the given target document. It can be inserted at any position in the tree.

Parameters:

• targetDocument (pdftools_toolbox.pdf.document.Document) – The output document with which the returned object is associated

• title (str) – The title of the newly created outline item.

• destination (Optional[pdftools_toolbox.pdf.navigation.destination.Destination]) – The destination that this outline item refers to or None if the item has no destination.

Returns:

The newly created outline item.

Return type:

pdftools_toolbox.pdf.navigation.outline_item.OutlineItem

Raises:

• ValueError – if the targetDocument argument has already been closed

• ValueError – if the targetDocument argument is read-only

• ValueError – if the document associated with the destination argument has already been closed

• ValueError – if the destination argument belongs to a different document

static copy(target_document: Document, outline_item: OutlineItem, options: OutlineCopyOptions | None) → OutlineItem

Copy an outline item

Copy an outline item object including all descendants from an input document to the given targetDocument. The returned object is associated with the given target document but not yet part of it.

Parameters:

• targetDocument (pdftools_toolbox.pdf.document.Document) – the output document with which the returned object is associated

• outlineItem (pdftools_toolbox.pdf.navigation.outline_item.OutlineItem) – An outline item of a different document

• options (Optional[pdftools_toolbox.pdf.navigation.outline_copy_options.OutlineCopyOptions]) – The options used to copy the item

Returns:

The copied outline item, associated with the current document.

Return type:

pdftools_toolbox.pdf.navigation.outline_item.OutlineItem

Raises:

• pdftools_toolbox.conformance_error.ConformanceError – The conformance level of the source document is not compatible with the conformance level of the target document.

• ValueError – if the targetDocument argument is None

• ValueError – if the targetDocument argument has already been closed

• ValueError – if the targetDocument argument is read-only

• ValueError – if the outlineItem argument is not associated with an input document

• ValueError – the target document contains implicitly copied outline items

• ValueError – the outlineItem argument is None

• ValueError – the outlineItem argument is not associated with an input document

• OSError – Error reading from the source document or writing to the target document

property title: str

The title of the outline item.

Returns:

str

Raises:

• StateError – the object has already been closed.

• StateError – the associated document has already been closed.

property bold: bool

If True, the outline item is displayed in bold font.

Returns:

bool

Raises:

• StateError – the object has already been closed.

• StateError – the associated document has already been closed.

property italic: bool

If True, the outline item is displayed in italic font.

Returns:

bool

Raises:

• StateError – the object has already been closed.

• StateError – the associated document has already been closed.

property destination: Destination | None

The destination of the outline item.

Returns:

Optional[pdftools_toolbox.pdf.navigation.destination.Destination]

Raises:

• StateError – the object has already been closed.

• StateError – the associated document has already been closed.

• OperationError – the object is not associated to an input document.

property is_open: bool

• If True, the item is expanded.

• If False, the item is collapsed.

This is property is only meaningful if the item has child items.

Returns:

bool

Raises:

• StateError – the object has already been closed.

• StateError – the associated document has already been closed.

property children: OutlineItemList

The child items of this outline item.

Returns:

pdftools_toolbox.pdf.navigation.outline_item_list.OutlineItemList

Raises:

• StateError – the object has already been closed.

• StateError – the associated document has already been closed.