Rich Text Document Structure

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->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.

     QTextBlock::iterator it;
     for (it = currentBlock.begin(); !(it.atEnd()); ++it) {
         QTextFragment currentFragment = it.fragment();
         if (currentFragment.isValid())
             processFragment(currentFragment);
     }

     QTextBlock currentBlock = textDocument->begin();

     while (currentBlock.isValid()) {
         processBlock(currentBlock);
         currentBlock = currentBlock.next();
     }

     QDomElement frameElement = ...

     QTextFrame::iterator it;
     for (it = frame->begin(); !(it.atEnd()); ++it) {

         QTextFrame *childFrame = it.currentFrame();
         QTextBlock childBlock = it.currentBlock();

         if (childFrame)
             processFrame(frameElement, childFrame);
         else if (childBlock.isValid())
             processBlock(frameElement, childBlock);
     }

     QDomElement frameElement = ...

     QTextFrame::iterator it;
     for (it = frame->begin(); !(it.atEnd()); ++it) {

         QTextFrame *childFrame = it.currentFrame();
         QTextBlock childBlock = it.currentBlock();

         if (childFrame) {
             QTextTable *childTable = qobject_cast<QTextTable*>(childFrame);

             if (childTable)
                 processTable(frameElement, childTable);
             else
                 processFrame(frameElement, childFrame);

         } else if (childBlock.isValid())
             processBlock(frameElement, childBlock);
     }

     for (int row = 0; row < table->rows(); ++row) {
         for (int column = 0; column < table->columns(); ++column) {
             QTextTableCell tableCell = table->cellAt(row, column);
             processTableCell(tableCell);
         }
     }

     for (int index = 0; index < list->count(); ++index) {
         QTextBlock listItem = list->item(index);
         processListItem(listItem);
     }

     QTextFrame::iterator it;
     for (it = frame->begin(); !(it.atEnd()); ++it) {

         QTextBlock block = it.currentBlock();

         if (block.isValid()) {

             QTextList *list = block.textList();

             if (list) {
                 int index = list->itemNumber(block);
                 processListItem(list, index);
             }
         }
     }

     if (fragment.isValid()) {
         QTextImageFormat newImageFormat = fragment.charFormat().toImageFormat();

         if (newImageFormat.isValid()) {
             newImageFormat.setName(":/images/newimage.png");
             QTextCursor helper = cursor;

             helper.setPosition(fragment.position());
             helper.setPosition(fragment.position() + fragment.length(),
                                 QTextCursor::KeepAnchor);
             helper.setCharFormat(newImageFormat);
         }
     }