Rich Text Document Structure▲
<Unknown command>contentspagerichtext.html Contents
Text documents are represented by the QTextDocument class, which contains information about the document's internal representation, its structure, and keeps track of modifications to provide undo/redo facilities.
The structured representation of a text document presents its contents as a hierarchy of text blocks, frames, tables, and other objects. These provide a logical structure to the document and describe how their contents will be displayed. Generally, frames and tables are used to group other structures while text blocks contain the actual textual information.
New elements are created and inserted into the document programmatically with a QTextCursor or by using an editor widget, such as QTextEdit. Elements can be given a particular format when they are created; otherwise they take the cursor's current format for the element.
|
Basic structure The "top level" of a document might be populated in the way shown. Each document always contains a root frame, and this always contains at least one text block. For documents with some textual content, the root frame usually contains a sequence of blocks and other elements. Sequences of frames and tables are always separated by text blocks in a document, even if the text blocks contain no information. This ensures that new elements can always be inserted between existing structures. |
In this chapter, we look at each of the structural elements used in a rich text document, outline their features and uses, and show how to examine their contents. Document editing is described in The QTextCursor Interface.
Rich Text Documents▲
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-&
gt;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-&
gt;rootFrame();
When navigating the document structure, it is useful to begin at the root frame because it provides access to the entire document structure.
Document Elements▲
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▲
Text blocks are provided by the QTextBlock class.
Text blocks group together fragments of text with different character formats, and are used to represent paragraphs in the document. Each block typically contain