The render module

Infrastructure for rendering and caching Page images.

class Tile(x, y, w, h)

Bases: tuple

Describes a tile to render. Most times all coordinates are integers. The needed tiles for a page are yielded by AbstractRenderer.tiles().


The height of the tile


The width of the tile


The x coordinate of the tile


The y coordinate of the tile

class Key(group, ident, rotation, width, height)

Bases: tuple

Identifies a render operation for a Page, returned by AbstractRenderer.key().


The group() of the page


The height of the page


The ident() of the page


The computedRotation of the page


The width of the page

class RenderInfo(images, missing, key, target, ratio)

Bases: tuple

Information about cached or missing rendered tiles to display a rectangular part of a Page at a certain size. Returned by


the devicepixelratio of the specified paint device


the Key returned by key(), describing width, height, rotation and identity of the page


a list of Tile instances that are needed but not available in the cache


Alias for field number 4


the rect multiplied by the ratio

class AbstractRenderer(cache=None)[source]

Bases: object

Handle rendering and caching of images.

A renderer can be assigned to the renderer attribute of a Page and takes care for generating, caching and updating the images needed for display of the Page at different sizes.

You can use a renderer for as many Page instances as you like. You can use one global renderer in your application or more, depending on how you use the qpageview package.

You must inherit from this class and at least implement the render() or the draw() method.

Instance attributes:


Paper color. If possible this background color is used when rendering the pages, also for temporary drawings when a page has to be rendered. If a Page specifies its own paperColor, that color prevails.


QImage format to use (if possible). Default is QImage.Format_ARGB32_Premultiplied


True by default. Whether to antialias graphics. (Most Renderers antialias anyway, even if this is False.)

paperColor = <PyQt5.QtGui.QColor object>
imageFormat = 6
antialiasing = True
cache = <qpageview.cache.ImageCache object>

Return a copy of the renderer, with always a new cache.

static key(page, ratio)[source]

Return a five-tuple Key describing the page.

The ratio is a device pixel ratio; width and height are multiplied with this value, to render and cache an image correctly on high- density displays.

This is used for rendering and caching. It is never stored as is. The cache can store the group object using a weak reference. The tuple contains the following values:


the object returned by


the value returned by page.ident()




page.width * ratio


page.height * ratio

tiles(width, height)[source]

Yield four-tuples Tile(x, y, w, h) describing the tiles to render.

map(key, box)[source]

Return a QTransform converting from Key coordinates to a box.

The box should be a QRectF or QRect, and describes the original area of the page. The returned matrix can be used to convert e.g. tile coordinates to the position on the original page.

image(page, rect, dpiX, dpiY, paperColor)[source]

Returns a QImage of the specified rectangle on the Page.

The rectangle is relative to the top-left position. The image is not cached.

render(page, key, tile, paperColor=None)[source]

Generate a QImage for tile of the Page.

The width, height and rotation to render at should be taken from the key, as the page could be resized or rotated in the mean time.

The default implementation prepares the image, a painter and then calls draw() to actually draw the contents.

If the paperColor is not specified, it will be read from the Page’s paperColor attribute (if not None) or else from the renderer’s paperColor attribute.

draw(page, painter, key, tile, paperColor=None)[source]

Draw the page contents; implement at least this method.

The painter is already at the top-left position and the correct rotation. You should convert the tile to the original area on the page, you can use the map() method for that. You can draw in tile/key coordinates. Don’t use width, height and rotation from the Page object, as it could have been resized or rotated in the mean time.

The paperColor can be speficied, but it is not needed to paint it: by default the render() method already fills the image, and when drawing on a printer, painting the background is normally not desired.

info(page, device, rect)[source]

Return a namedtuple RenderInfo(images, missing, key, target, ratio).

images is a list of tuples (tile, image) that are available in the cache; missing is a list of Tile instances that are not available in the cache; key is the Key returned by key(), describing width, height, rotation and identity of the page; target is the rect multiplied by the ratio; which is the devicepixelratio of the specified paint device.

update(page, device, rect, callback=None)[source]

Check if a page can be painted on the device without waiting.

Return True if that is the case. Otherwise schedules missing tiles for rendering and calls the callback each time one tile if finished.

paint(page, painter, rect, callback=None)[source]

Paint a page, using images from the cache.


the Page to draw


the QPainter to use to draw


the region to draw, relative to the topleft of the page.


if specified, a callable accepting the page argument. Typically this should be used to trigger a repaint of the view.

The Page calls this method by default in its paint() method. This method tries to fetch an image from the cache and paint that. If no image is available, render() is called in the background to generate one. If it is ready, the callback is called with the Page as argument. An interim image may be painted in the meantime (e.g. scaled from another size).

schedule(page, key, tiles, callback)[source]

Schedule a new rendering job for the specified tiles of the page.

If this page has already a job pending, the callback is added to the pending job.

job(page, key, tile)[source]

Return a new Job tailored for this tile.

unschedule(pages, callback)[source]

Unschedule a possible pending rendering job for the given pages.

If the pending job has no other callbacks left, it is removed, unless it is running.


Delete the cached images for the given pages.


Check whether there are jobs that need to be started.

This method is called by the schedule() method, and by the finish() method when a job finishes, so that the number of running jobs never exceeds maxjobs.

exception(exctype, excvalue, exctb)[source]

Called when an exception has occurred in a background rendering job.

The default implementation prints a traceback to stderr.