The document module

Document, a simple class representing a group of pages.

It is certainly not necessary to use a Document to handle pages in a View, but it might be convenient in some cases.

The Document class can be used to manually build a document consisting of a group of pages, that can be specified on construction or added to the list returned by the Document.pages() method.

Then two subtypes exist, SingleSourceDocument and MultiSourceDocument, that can be subclassed into document types that either load every Page from a single file or, respectively, load all pages from one filename.

Instead of a filename, any object can be used as data source. Depending on the page type, a QIODevice or QByteArray could be used.

Instantiating a Document is very fast, as nothing is loaded or computed on instantiation. Only when pages() is called for the first time, file contents are loaded, which normally happens when a Document is shown in a View using View.setDocument().

class Document(pages=())

Bases: object

A Document represents a group of pages that belong together in some way.

Add pages on creation or by manipulating the list returned by pages().

count()

Return the number of pages.

pages()

Return the list of pages.

clear()

Empties the document.

filename()

Return the filename of the document.

The default implementation returns an empty string.

filenames()

Return the list of filenames, for multi-file documents.

The default implementation returns an empty list.

urls()

Return a dict, mapping URLs (str) to areas on pages.

This method queries the links of all pages, and if they have a URL, the area attribute of that link is added to a list for every page, and every unique URL is mapped to a dict, that maps page number to the list of areas on that page (page numbers start with 0).

In the returned dict you can quickly find the areas in which a URL appears in a link.

addUrls(urls)

Read the dict (such as returned by urls()) and make clickable links.

This can be used to add url-links to a document from another document, e.g. when a document represents the same content, but has no clickable links (e.g. images). Links on pages with a higher number than our number of pages are skipped.

class AbstractSourceDocument(renderer=None)

Bases: qpageview.document.Document

A Document that loads pages from external source, such as a file.

The pages are loaded on first request, and invalidate can be called to trigger a reload.

pages()

Return the list of Pages, creating them at first call.

invalidate()

Delete all cached pages, except for filename(s) or source object(s).

Also called internally by clear().

clear()

Delete all cached pages, and clear filename(s) or source object(s).

createPages()

Implement this method to create and yield the pages.

This method is only called once. After altering filename,-s or source,-s, or invalidate(), it is called again.

urls()

Reimplemented to cache the urls returned by Document.urls().

class SingleSourceDocument(source=None, renderer=None)

Bases: qpageview.document.AbstractSourceDocument

A Document that loads its pages from a single file or source.

source()

Return a data object that might be set for the whole document.

setSource(source)

Set the data object for the whole document. Invalidates the document.

filename()

Return the file name applying to the whole document.

setFilename(source)

Set the data object for the whole document. Invalidates the document.

clear()

Delete all cached pages, and clear filename or source object.

class MultiSourceDocument(sources=(), renderer=None)

Bases: qpageview.document.AbstractSourceDocument

A Document that loads every page from its own file or source.

sources()

Return data objects for every page.

setSources(sources)

Set data objects for every page. Invalidates the document.

filenames()

Return the list of file names of every page.

setFilenames(sources)

Set data objects for every page. Invalidates the document.

clear()

Delete all cached pages, and clear filenames or source objects.