pdftools_toolbox.pdf.navigation.location_zoom_destination

Classes

LocationZoomDestination(handle)

A destination that points to a specific location on the target page, using a specified zoom factor.
class pdftools_toolbox.pdf.navigation.location_zoom_destination.LocationZoomDestination(handle)[source]

Bases: DirectDestination

A destination that points to a specific location on the target page, using a specified zoom factor. The location is displayed in the top left corner of the viewport (if possible).

static create(target_document: Document, page: Page, left: float | None, top: float | None, zoom: float | None) → LocationZoomDestination[source]

Create a new LocationZoomDestination

The returned object is not yet used on any page, but it is associated with the given target document.

Parameters:
Returns:

The newly created destination object.

Return type:

pdftools_toolbox.pdf.navigation.location_zoom_destination.LocationZoomDestination

Raises:

  • ValueError – if the targetDocument argument has already been closed

  • ValueError – if the targetDocument argument is read-only

  • ValueError – if the targetDocument`differs from the document associated with `page

  • ValueError – If the document associated with the page argument has already been closed

property left: float | None

The location of the page that is displayed at the left border of the viewport (if possible).

If the property is None, the value from before the jump is retained.

Note: Due to the current zoom factor, it is usually not possible for viewers to scroll as far to the right side, as would be necessary to place the location at the left corner of the viewport. However, viewers will ensure, that the location is at least visible.

In practice this means, that this value is mostly irrelevant.

Returns:

Optional[float]

Raises:

  • StateError – the object has already been closed.

  • StateError – the associated document has already been closed.

property top: float | None

The location of the page that is displayed at the top of the viewport (if possible).

If the property is None, the value from before the jump is retained.

Returns:

Optional[float]

Raises:

  • StateError – the object has already been closed.

  • StateError – the associated document has already been closed.

property zoom: float | None

The zoom factor that is applied when jumping to the destination.

A value of None means that the current zoom level is retained.

Note: Many PDF viewers support different viewing modes like “fit page” or “fit width”.

A pdftools_toolbox.pdf.navigation.location_zoom_destination.LocationZoomDestination with a pdftools_toolbox.pdf.navigation.location_zoom_destination.LocationZoomDestination.zoom value of None will usually not change the current viewing mode in most viewers.

For other pdftools_toolbox.pdf.navigation.location_zoom_destination.LocationZoomDestination.zoom values however, the viewer must switch to the standard mode, i.e. deactivate special modes like “fit page” or “fit width”.

Because of this, using a pdftools_toolbox.pdf.navigation.location_zoom_destination.LocationZoomDestination.zoom value other than None is discouraged.

Returns:

Optional[float]

Raises:

  • StateError – the object has already been closed.

  • StateError – the associated document has already been closed.