Rich Text Document Structure

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 contains a number of text fragments with different styles. Fragments are created when text is inserted into the document, and more of them are added when the document is edited. The document splits, merges, and removes fragments to efficiently represent the different styles of text in the block.

The fragments within a given block can be examined by using a QTextBlock::iterator to traverse the block's internal structure:

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

Blocks are also used to represent list items. As a result, blocks can define their own character formats which contain information about block-level decoration, such as the type of bullet points used for list items. The formatting for the block itself is described by the QTextBlockFormat class, and describes properties such as text alignment, indentation, and background color.

Although a given document may contain complex structures, once we have a reference to a valid block in the document, we can navigate between each of the text blocks in the order in which they were written:

     QTextBlock currentBlock = textDocument->begin();

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

This method is useful for when you want to extract just the rich text from a document because it ignores frames, tables, and other types of structure.

QTextBlock provides comparison operators that make it easier to manipulate blocks: operator==() and operator!=() are used to test whether two blocks are the same, and operator<() is used to determine which one occurs first in a document.

     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);
     }

     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);
         }
     }