The view module

The View, deriving from QAbstractScrollArea.

class Position(pageNumber, x, y)

Bases: tuple

pageNumber

Alias for field number 0

x

Alias for field number 1

y

Alias for field number 2

class View(parent=None, **kwds)

Bases: qpageview.scrollarea.ScrollArea

View is a generic scrollable widget to display Pages in a layout.

Using setPageLayout() you can set a PageLayout to the View, and you can add Pages to the layout using a list-like api. (PageLayout derives from list). A simple PageLayout is set by default. Call updatePageLayout() after every change to the layout (like adding or removing pages).

You can also add a Magnifier to magnify parts of a Page, and a Rubberband to enable selecting a rectangular region.

View emits the following signals:

pageCountChanged (int)

emitted when the total amount of pages has changed

currentPageNumberChanged (int)

emitted when the current page number has changed (starting with 1)

viewModeChanged (int)

emitted when the viewMode has changed

rotationChanged (int)

emitted when the rotation has changed

orientationChanged (int)

emitted when the orientation has changed

zoomFactorChanged (float)

emitted when the zoomFactor has changed

continuousModeChanged (bool)

emitted when the continuousMode has changed

pageLayoutModeChanged (str)

emitted when the pageLayoutMode has changed

pageLayoutUpdated ()

emitted whenever the page layout has been updated (redraw/resize)

MIN_ZOOM = 0.05

MAX_ZOOM = 64.0

wheelZoomingEnabled = True

whether to enable mouse wheel zooming

kineticPagingEnabled = True

whether to enable kinetic scrolling while paging (setCurrentPageNumber)

pagingOnScrollEnabled = True

whether to keep track of current page while scrolling

clickToSetCurrentPageEnabled = True

whether a mouse click in a page makes it the current page

strictPagingEnabled = False

whether PageUp and PageDown call setCurrentPageNumber instead of scroll

documentPropertyStore = None

can be set to a DocumentPropertyStore object. If set, the object is used to store certain View settings on a per-document basis. (This happens in the clear() and setDocument() methods.)

pageCountChanged

(int) emitted when the total amount of pages has changed

currentPageNumberChanged

(int) emitted when the current page number has changed (starting with 1)

viewModeChanged

(int) emitted when the viewMode has changed

rotationChanged

(int) emitted when the rotation has changed

orientationChanged

(int) emitted when the orientation has changed

zoomFactorChanged

(float) emitted when the zoomFactor has changed

continuousModeChanged

(bool) emitted when the continuousMode has changed

pageLayoutModeChanged

(str) emitted when the pageLayoutMode has changed

pageLayoutUpdated

emitted whenever the page layout has been updated (redraw/resize)

pageCount()

Return the number of pages in the view.

currentPageNumber()

Return the current page number in view (starting with 1).

setCurrentPageNumber(num)

Scrolls to the specified page number (starting with 1).

If the page is already in view, the view is not scrolled, otherwise the view is scrolled to center the page. (If the page is larger than the view, the top-left corner is positioned top-left in the view.)

updateCurrentPageNumber(num)

Set the current page number without scrolling the view.

gotoNextPage()

Convenience method to go to the next page.

gotoPreviousPage()

Convenience method to go to the previous page.

currentPage()

Return the page pointed to by currentPageNumber().

page(num)

Return the page at the specified number (starting at 1).

pages()

Return a list of all Pages in the page layout.

position()

Return a three-tuple Position(pageNumber, x, y).

The Position describes where the center of the viewport is on the layout. The page is the page number (starting with 1) and x and y the position on the page, in a 0..1 range. This way a position can be remembered even if the zoom or orientation of the layout changes.

setPosition(position, allowKinetic=True)

Centers the view on the spot stored in the specified Position.

If allowKinetic is False, immediately jumps to the position, otherwise scrolls smoothly (if kinetic scrolling is enabled).

setPageLayout(layout)

Set our current PageLayout instance.

The dpiX and dpiY attributes of the layout are set to the physical resolution of the widget, which should result in a natural size of 100% at zoom factor 1.0.

pageLayout()

Return our current PageLayout instance.

pageLayoutModes()

Return a dictionary mapping names to callables.

The callable returns a configured LayoutEngine that is set to the page layout. You can reimplement this method to returns more layout modes, but it is required that the name “single” exists.

pageLayoutMode()

Return the currently set page layout mode.

setPageLayoutMode(mode)

Set the page layout mode.

The mode is one of the names returned by pageLayoutModes(). The mode name “single” is guaranteed to exist.

updatePageLayout(lazy=False)

Update layout, adjust scrollbars, keep track of page count.

If lazy is set to True, calls lazyUpdate() to update the view.

modifyPages()

Return the list of pages and enter a context to make modifications.

Note that the first page is at index 0. On exit of the context the page layout is updated.

modifyPage(num)

Return the page (numbers start with 1) and enter a context.

On exit of the context, the page layout is updated.

clear()

Convenience method to clear the current layout.

setPages(pages)

Load the iterable of pages into the View.

Existing pages are removed, and the document is set to None.

setDocument(document)

Set the Document to display (see document.Document).

document()

Return the Document currently displayed (see document.Document).

reload()

If a Document was set, invalidate()s it and then reloads it.

loadPdf(filename, renderer=None)

Convenience method to load the specified PDF file.

The filename can also be a QByteArray or an already loaded popplerqt5.Poppler.Document instance.

loadSvgs(filenames, renderer=None)

Convenience method to load the specified list of SVG files.

Each SVG file is loaded in one Page. A filename can also be a QByteArray.

loadImages(filenames, renderer=None)

Convenience method to load images from the specified list of files.

Each image is loaded in one Page. A filename can also be a QByteArray or a QImage.

print(printer=None, pageNumbers=None, showDialog=True)

Print all, or speficied pages to QPrinter printer.

If given the pageNumbers should be a list containing page numbers starting with 1. If showDialog is True, a print dialog is shown, and printing is canceled when the user cancels the dialog.

If the QPrinter to use is not specified, a default one is created. The print job is started and returned (a printing.PrintJob instance), so signals for monitoring the progress could be connected to. (If the user cancels the dialog, no print job is returned.)

static properties()

Return an uninitialized ViewProperties object.

readProperties(settings)

Read View settings from the QSettings object.

If a documentPropertyStore is set, the settings are also set as default for the DocumentPropertyStore.

writeProperties(settings)

Write the current View settings to the QSettings object.

If a documentPropertyStore is set, the settings are also set as default for the DocumentPropertyStore.

setViewMode(mode)

Sets the current ViewMode.

viewMode()

Returns the current ViewMode.

setRotation(rotation)

Set the current rotation.

rotation()

Return the current rotation.

rotateLeft()

Rotate the pages 270 degrees.

rotateRight()

Rotate the pages 90 degrees.

setOrientation(orientation)

Set the orientation (Horizontal or Vertical).

orientation()

Return the current orientation (Horizontal or Vertical).

setContinuousMode(continuous)

Sets whether the layout should display all pages.

If True, the layout shows all pages. If False, only the page set containing the current page is displayed. If the pageLayout() does not support the PageSetLayoutMixin methods, this method does nothing.

continuousMode()

Return True if the layout displays all pages.

displayPageSet(what)

Try to display a page set (if the layout is not in continuous mode).

what can be:

“next”: go to the next page set “previous”: go to the previous page set “first”: go to the first page set “last”: go to the last page set integer: go to the specified page set

setMagnifier(magnifier)

Sets the Magnifier to use (or None to disable the magnifier).

The viewport takes ownership of the Magnifier.

magnifier()

Returns the currently set magnifier.

setRubberband(rubberband)

Sets the Rubberband to use for selections (or None to not use one).

rubberband()

Return the currently set rubberband.

pagingOnScrollDisabled()

During this context a scroll is not tracked to update the current page number.

scrollContentsBy(dx, dy)

Reimplemented to move the rubberband and adjust the mouse cursor.

stopScrolling()

Reimplemented to adjust the mouse cursor on scroll stop.

fitPageLayout()

Fit the layout according to the view mode.

Does nothing in FixedScale mode. Prevents scrollbar/resize loops by precalculating which scrollbars will appear.

keepCentered(pos=None)

Context manager to keep the same spot centered while changing the layout.

If pos is not given, the viewport’s center is used. After yielding, updatePageLayout() is called.

setZoomFactor(factor, pos=None)

Set the zoom factor (1.0 by default).

If pos is given, that position (in viewport coordinates) is kept in the center if possible. If None, zooming centers around the viewport center.

zoomFactor()

Return the page layout’s zoom factor.

zoomIn(pos=None, factor=1.1)

Zoom in.

If pos is given, it is the position in the viewport to keep centered. Otherwise zooming centers around the viewport center.

zoomOut(pos=None, factor=1.1)

Zoom out.

If pos is given, it is the position in the viewport to keep centered. Otherwise zooming centers around the viewport center.

zoomNaturalSize(pos=None)

Zoom to the natural pixel size of the current page.

The natural pixel size zoom factor can be different than 1.0, if the screen’s DPI differs from the current page’s DPI.

layoutPosition()

Return the position of the PageLayout relative to the viewport.

This is the top-left position of the layout, relative to the top-left position of the viewport.

If the layout is smaller than the viewport it is centered by default. (See ScrollArea.alignment.)

visibleRect()

Return the QRect of the page layout that is currently visible in the viewport.

visiblePages(rect=None)

Yield the Page instances that are currently visible.

If rect is not given, the visibleRect() is used. The pages are sorted so that the pages with the largest visible part come first.

ensureVisible(rect, margins=None, allowKinetic=True)

Ensure rect is visible, switching page set if necessary.

adjustCursor(pos)

Sets the correct mouse cursor for the position on the page.

repaintPage(page)

Call this when you want to redraw the specified page.

lazyUpdate(page=None)

Lazily repaint page (if visible) or all visible pages.

Defers updating the viewport for a page until all rendering tasks for that page have finished. This reduces flicker.

rerender(page=None)

Schedule the specified page or all pages for rerendering.

Call this when you have changed render options or page contents. Repaints the page or visible pages lazily, reducing flicker.

pagesToPaint(rect, painter)

Yield (page, rect) to paint in the specified rectangle.

The specified rect is in viewport coordinates, as in the paint event. The returned rect describes the part of the page actually to draw, in page coordinates. (The full rect can be found in page.rect().) Translates the painter to the top left of each page.

The pages are sorted with largest area last.

event(ev)

Reimplemented to get Gesture events.

handleGestureEvent(event)

Gesture event handler.

Return False if event is not accepted. Currently only cares about PinchGesture. Could also handle Swipe and Pan gestures.

pinchGesture(gesture)

Pinch gesture event handler.

Return False if event is not accepted. Currently only cares about ScaleFactorChanged and not RotationAngleChanged.

paintEvent(ev)

Paint the contents of the viewport.

resizeEvent(ev)

Reimplemented to scale the view if needed and update the scrollbars.

wheelEvent(ev)

Reimplemented to support wheel zooming and paging through page sets.

mousePressEvent(ev)

Implemented to set the clicked page as current, without moving it.

mouseMoveEvent(ev)

Implemented to adjust the mouse cursor depending on the page contents.

keyPressEvent(ev)

Reimplemented to go to next or previous page set if possible.

class ViewProperties

Bases: object

Simple helper class encapsulating certain settings of a View.

The settings can be set to and got from a View, and saved to or loaded from a QSettings group.

Class attributes serve as default values, None means: no change. All methods return self, so operations can easily be chained.

If you inherit from a View and add more settings, you can also add properties to this class by inheriting from it. Reimplement View.properties() to return an instance of your new ViewProperties subclass.

position = None

rotation = 0

zoomFactor = 1.0

viewMode = 0

orientation = None

continuousMode = None

pageLayoutMode = None

setdefaults()

Set all properties to default values. Also used by View on init.

copy()

Return a copy or ourselves.

names()

Return a tuple with all the property names we support.

mask(names)

Set properties not listed in names to None.

get(view)

Get the properties of a View.

set(view)

Set all our properties that are not None to a View.

save(settings)

Save the properties that are not None to a QSettings group.

load(settings)

Load the properties from a QSettings group.

class DocumentPropertyStore

Bases: object

Store ViewProperties (settings) on a per-Document basis.

If you create a DocumentPropertyStore and install it in the documentPropertyStore attribute of a View, the View will automatically remember its settings for earlier displayed Document instances.

default = None

mask = None

get(document)

Get the View properties stored for the document, if available.

If a ViewProperties instance is stored in the default attribute, it is returned when no properties were available. Otherwise, None is returned.

set(document, properties)

Store the View properties for the document.

If the mask attribute is set to a list or tuple of names, only the listed properties are remembered.