The page module

A Page is responsible for drawing a page inside a PageLayout.

class AbstractPage

Bases: qpageview.util.Rectangular

A Page is a rectangle that is positioned in a PageLayout.

A Page represents one page, added to a PageLayout that is displayed in a View. Although there is no mechanism to enforce it, a Page is normally only used in one PageLayout at a time.

A Page has instance attributes:

• that normally do not change during its lifetime:

  pageWidth

  the original width (by default in points, dpi is 72.0

  pageHeight

  the original height but can be changed at class level)

• that can be modified by the user (having defaults at the class level):

  scaleX

  the scale in X-direction of the original page (1.0)

  scaleY

  the scale in Y-direction of the original page (1.0)

  rotation

  the rotation (Rotate_0)

  z

  the z-index (0) (only relevant when pages overlap)

  paperColor

  the paper color (None). If None, the renderer’s paperColor is used.

• and that are set by the layout when computing the size and positioning the pages:

  x

  the position x-coordinate

  y

  the position y-coordinate

  width

  the width in pixels

  height

  the height in pixels

  computedRotation

  the rotation in which finally to render

The class variable dpi is 72.0 by default but can be set to a different value depending on the page type. E.g. for Svg pages 90 or 96 makes sense.

renderer = None

dpi = 72.0

pageWidth = 595.28

pageHeight = 841.89

z = 0

rotation = 0

computedRotation = 0

scaleX = 1.0

scaleY = 1.0

paperColor = None

classmethod load(filename, renderer=None)

Implement this to yield one or more pages by reading the file.

The renderer may be None, and not all page types use a renderer. The filename may be a string or a QByteArray object containing the data.

classmethod loadFiles(filenames, renderer=None)

Load multiple files, yielding Page instances of this type.

copy(owner=None, matrix=None)

Return a copy of the page with the same instance attributes.

If owner is specified, the copy is weakly cached for that owner and returned next time. All instance attribute will be updated each time. If matrix is specified, it should be a QTransform, and it will be used to map the geometry of the original to the (cached) copy before it is returned.

setPageSize(sizef)

Set our natural page size (QSizeF).

Normally this is done in the constructor, based on the page we need to render.

By default the page size is assumed to be in points, 1/72 of an inch. You can set the dpi class variable to use a different unit.

pageSize()

Return our natural page size (QSizeF).

By default the page size is assumed to be in points, 1/72 of an inch. You can set the dpi class variable to use a different unit.

pageRect()

Return QRectF(0, 0, pageWidth, pageHeight).

transform(width=None, height=None)

Return a QTransform, converting an original area to page coordinates.

The width and height refer to the original (unrotated) width and height of the page’s contents, and default to pageWidth and pageHeight.

defaultSize()

Return the pageSize() scaled and rotated (if needed).

Based on scaleX, scaleY, and computedRotation attributes.

updateSize(dpiX, dpiY, zoomFactor)

Set the width and height attributes of the page.

This size is computed based on the page’s natural size, dpi, scale and computedRotation attribute; and the supplied dpiX, dpiY, and zoomFactor.

zoomForWidth(width, rotation, dpiX)

Return the zoom we need to display ourselves at the given width.

zoomForHeight(height, rotation, dpiY)

Return the zoom we need to display ourselves at the given height.

paint(painter, rect, callback=None)

Implement this to paint our Page.

The View calls this method in the paint event. If you can’t paint quickly, just return and schedule an image to be rendered in the background. If a callback is specified, it is called when the image is ready with the page as argument.

print(painter, rect=None, paperColor=None)

Implement this to paint a page for printing.

The difference with paint() and image() is that the rect (QRectF) supplied to print() is not in the Page coordinates, but in the original pageSize() and unrotated. The painter has been prepared for scale and rotation.

If rect is None, the full pageRect() is used.

output(device, rect=None, paperColor=None)

Paint specified rectangle (or the whole page) to the paint device.

The page is rotated and scaled, and the resolution of the paint device is used in case pixelbased images need to be generated. But where possible, vector painting is used.

This method uses print() to do the actual painting to the paint device. If paperColor is not given, no background is printed normally.

image(rect=None, dpiX=None, dpiY=None, paperColor=None)

Implement this to return a QImage of the specified rectangle.

The rectangle is relative to our top-left position. dpiX defaults to our default dpi and dpiY defaults to dpiX.

pdf(filename, rect=None, resolution=72.0, paperColor=None)

Create a PDF file for the selected rect or the whole page.

The filename may be a string or a QIODevice object. The rectangle is relative to our top-left position. Normally vector graphics are rendered, but in cases where that is not possible, the resolution will be used to determine the DPI for the generated rendering.

eps(filename, rect=None, resolution=72.0, paperColor=None)

Create a EPS (Encapsulated Postscript) file for the selected rect or the whole page.

This needs the popplerqt5 module. The filename may be a string or a QIODevice object. The rectangle is relative to our top-left position. Normally vector graphics are rendered, but in cases where that is not possible, the resolution will be used to determine the DPI for the generated rendering.

svg(filename, rect=None, resolution=72.0, paperColor=None)

Create a SVG file for the selected rect or the whole page.

The filename may be a string or a QIODevice object. The rectangle is relative to our top-left position. Normally vector graphics are rendered, but in cases where that is not possible, the resolution will be used to determine the DPI for the generated rendering.

pixmap(rect=None, size=100, paperColor=None)

Return a QPixmap, scaled so that width or height doesn’t exceed size.

Uses the image() method to get the image, and converts that to a QPixmap.

mutex()

Return an object that should be locked when rendering the page.

Page are guaranteed not to be rendered at the same time when they return the same mutex object. By default, None is returned.

group()

Return the group the page belongs to.

This could be some document structure, so that different Page objects could refer to the same graphical contents, preventing double caching.

This object is used together with the value returned by ident() as a key to cache the page. The idea is that the contents of the page are uniquely identified by the objects returned by group() and ident().

This way, when the same document is opened in multiple page instances, only one copy resides in the (global) cache.

By default, the page object itself is returned.

ident()

Return a value that identifies the page within the group returned by group().

By default, None is returned.

mapToPage(width=None, height=None)

Return a MapToPage object, that can map original to Page coordinates.

The width and height refer to the original (unrotated) width and height of the page’s contents, and default to pageWidth and pageHeight.

mapFromPage(width=None, height=None)

Return a MapFromPage object, that can map Page to original coordinates.

The width and height refer to the original (unrotated) width and height of the page’s contents, and default to pageWidth and pageHeight.

text(rect)

Implement this method to get the text at the specified rectangle.

The rectangle should be in page coordinates. The default implementation simply returns an empty string.

getLinks()

Implement this method to load our links.

links()

Return the Links object, containing Link objects.

Every Link denotes a clickable area on a Page, in coordinates 0.0-1.0. The Links object makes it possible to quickly find a link on a Page. This is cached after the first request, you should implement the getLinks() method to load the links.

linksAt(point)

Return a list of zero or more links touched by QPoint point.

The point is in page coordinates. The list is sorted with the smallest rectangle first.

linksIn(rect)

Return an unordered set of links enclosed in rectangle.

The rectangle is in page coordinates.

linkRect(link)

Return a QRect encompassing the linkArea of a link in coordinates of our page.

class AbstractRenderedPage(renderer=None)

Bases: qpageview.page.AbstractPage

A Page that has a renderer that performs caching and painting.

The renderer lives in the renderer attribute.

paint(painter, rect, callback=None)

Reimplement this to paint our Page.

The View calls this method in the paint event. If you can’t paint quickly, just return and schedule an image to be rendered in the background. If a callback is specified, it is called when the image is ready with the page as argument.

By default, this method calls the renderer’s paint() method.

print(painter, rect=None, paperColor=None)

Paint a page for printing.

The difference with paint() and image() is that the rect (QRectF) supplied to print() is not in the Page coordinates, but in the original pageSize() and unrotated. The painter has been prepared for scale and rotation.

If rect is None, the full pageRect() is used. This method calls the renderer’s draw() method.

image(rect=None, dpiX=None, dpiY=None, paperColor=None)

Returns a QImage of the specified rectangle.

The rectangle is relative to our top-left position. dpiX defaults to our default dpi and dpiY defaults to dpiX. This implementation calls the renderer to generate the image. The image is not cached.

class BlankPage

Bases: qpageview.page.AbstractPage

A blank page.

paint(painter, rect, callback=None)

Paint blank page in the View.

print(painter, rect=None, paperColor=None)

Paint blank page for printing.

image(rect=None, dpiX=None, dpiY=None, paperColor=None)

Return a blank image.

class ImagePrintPageMixin

Bases: object

A Page mixin that implements print() using the image() method.

This can be used e.g. for compositing pages, which does not work well when painting to a PDF, a printer or a SVG generator.

print(painter, rect=None, paperColor=None)

Print using the image() method.