The document module

This module implements a Document encapsulating a QTextDocument.

It is not needed to store the Document itself, it is only used to modify the QTextDocument through the parce.Document API.

We do not ourself retokenize the text, that is done by a TreeBuilder that is automatically connected to the document.

class Document(root_lexicon=None, text='', url=None, encoding=None, worker=None, transformer=None)

Bases: DocumentInterface

Document accesses a QTextDocument via the parce.Document API.

There are two ways to construct a Document, and both use the default constructor. The first and default way is calling the constructor with the same arguments as the parce.Document constructor. This way a QTextDocument is created as well, containing the text. Only that QTextDocument actually needs to be kept; there is no need to store the Document object, it is only used to access and modify the contents of a QTextDocument. An example:

>>> d = parceqt.Document(MyLang.root, "text")
>>> d.document()
<PyQt5.QtGui.QTextDocument object at 0x7f6706473c10>

The second way is to call the constructor with the QTextDocument as the first argument. This creates also a new Document instance, but it wraps the existing QTextDocument, so that it can be accessed (again) via the parce API.

>>> d = Document(doc)   # where doc is an existing QTextDocument
>>> with d:
...     d[5:5] = 'some text'

This is useful when you have written code that manipulates text files based on the tokenized tree via the parce.Document API, you can use the same code to manipulate QTextDocuments, e.g. in a GUI editor.

Just like with parce.Document, updating the token tree (and the transformed result) is handled by a Worker, which in parceqt is a QObject that lives as long as the QTextDocument, in the background, as a child of it.

The url property is stored in the QTextDocument’s meta information; the encoding property is currently not retained when a Document is instantiated again.

It is not necessary to supply a worker, because in parceqt the Worker is a child object of the QTextDocument and instantiated automatically by this constructor.

set_formatter(formatter)

Set a Formatter to enable syntax highlighting.

If formatter is None, highlighting is effectively disabled. If False, the SyntaxHighlighter is deleted if active.

Example:

>>> import parce
>>> import parceqt
>>> # of course create QApplication etc...
>>> f = parceqt.Formatter(parce.theme_by_name('default'))
>>> d = parceqt.Document.load("my_file.css")
>>> d.set_formatter(f)

The same Formatter can be used for multiple documents.

formatter()

Return the Formatter that is used for syntax highlighting.

Returns None if no formatter was set.

property url

The url of this document, stored in QTextDocument’s meta information.

property revision

The QTextDocument’s revision.

property modified

Whether the QTextDocument is modified.

document()

Return our QTextDocument.

text()

Reimplemented to get the text from the QTextDocument.

text_changed(start, removed, added)

Reimplemented to do nothing, it is already handled by TreeBuilder.

find_start_of_block(position)

Reimplemented to use QTextDocument’s TextBlock.

find_end_of_block(position)

Reimplemented to use QTextDocument’s TextBlock.

class Cursor(document, pos=0, end=-1)

Bases: Cursor

A cursor with a textCursor() method to return a QTextCursor.

Only use this Cursor with parceqt.Document.

textCursor()

Return a QTextCursor for our document with the same position and selection.

(This method uses the Qt camelCase naming convention.)

html()

Return the selected range as HTML.

Uses the same theme(s) as the highlighter (if active).

copy_html()

Copy the selected range as HTML to the Qt clipboard.