Rich Text Document Structure

QTextDocument objects contain all the information required to construct rich text documents. Text documents can be accessed in two complementary ways: as a linear buffer for editors to use, and as an object hierarchy that is useful to layout engines. In the hierarchical document model, objects generally correspond to visual elements such as frames, tables, and lists. At a lower level, these elements describe properties such as the text style and alignment. The linear representation of the document is used for editing and manipulation of the document's contents.

Although QTextEdit makes it easy to display and edit rich text, documents can also be used independently of any editor widget, for example:

QTextDocument *newDocument = new QTextDocument;

Alternatively, they can be extracted from an existing editor:

QTextEdit *editor = new QTextEdit;
QTextDocument *editorDocument = editor->document();

This flexibility enables applications to handle multiple rich text documents without the overhead of multiple editor widgets, or requiring documents to be stored in some intermediate format.

An empty document contains a root frame which itself contains a single empty text block. Frames provide logical separation between parts of the document, but also have properties that determine how they will appear when rendered. A table is a specialized type of frame that consists of a number of cells, arranged into rows and columns, each of which can contain further structure and text. Tables provide management and layout features that allow flexible configurations of cells to be created.

Text blocks contain text fragments, each of which specifies text and character format information. Textual properties are defined both at the character level and at the block level. At the character level, properties such as font family, text color, and font weight can be specified. The block level properties control the higher level appearance and behavior of the text, such as the direction of text flow, alignment, and background color.

The document structure is not manipulated directly. Editing is performed through a cursor-based interface. The text cursor interface automatically inserts new document elements into the root frame, and ensures that it is padded with empty blocks where necessary.

We obtain the root frame in the following manner:

    QTextDocument *textDocument;
    QTextFrame *root = textDocument->rootFrame();

When navigating the document structure, it is useful to begin at the root frame because it provides access to the entire document structure.

Rich text documents usually consist of common elements such as paragraphs, frames, tables, and lists. These are represented in a QTextDocument by the QTextBlock, QTextFrame, QTextTable, and QTextList classes. Unlike the other elements in a document, images are represented by specially formatted text fragments. This enables them to be placed formatted inline with the surrounding text.

The basic structural building blocks in documents are QTextBlock and QTextFrame. Blocks themselves contain fragments of rich text (QTextFragment), but these do not directly influence the high level structure of a document.

Elements which can group together other document elements are typically subclasses of QTextObject, and fall into two categories: Elements that group together text blocks are subclasses of QTextBlockGroup, and those that group together frames and other elements are subclasses of QTextFrame.

Text Blocks▲