FCL/sf/mw/qt: comparison doc/src/frameworks-technologies/richtext.qdoc

equal deleted inserted replaced

-:41300fa6a67c
+:f7bc934e204c
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\group richtext-processing
+\title Rich Text Processing APIs
+*/
+/*!
+\page richtext.html
+\title Rich Text Processing
+\brief An overview of Qt's rich text processing, editing and display features.
+\ingroup frameworks-technologies
+\nextpage Rich Text Document Structure
+The Scribe framework provides a set of classes for reading and manipulating
+structured rich text documents. Unlike previous rich text support in Qt, the
+new classes are centered around the QTextDocument class rather than raw
+textual information. This enables the developer to create and modify
+structured rich text documents without having to prepare content in an
+intermediate markup format.
+The information within a document can be accessed via two complementary
+interfaces: A cursor-based interface is used for editing, and a read-only
+hierarchical interface provides a high level overview of the document
+structure. The main advantage of the cursor-based interface is that the
+text can be edited using operations that mimic a user's interaction with
+an editor, without losing the underlying structure of the document. The
+read-only hierarchical interface is most useful when performing operations
+such as searching and document export.
+This document is divided up into chapters for convenient reference:
+\list
+\i \l{Rich Text Document Structure} outlines
+the different kinds of elements in a QTextDocument, and describes how
+they are arranged in a document structure.
+\i \l{The QTextCursor Interface} explains how rich
+text documents can be edited using the cursor-based interface.
+\i \l{Document Layouts} briefly explains the role of document layouts.
+\i \l{Common Rich Text Editing Tasks} examines some
+common tasks that involve reading or manipulating rich text documents.
+\i \l{Advanced Rich Text Processing} examines advanced rich text editing tasks.
+\i \l{Supported HTML Subset} lists the HTML tags supported by QTextDocument.
+\endlist
+\section1 Rich Text Processing APIs
+Qt provides an extensive collection of classes for parsing, rendering
+manipulating and editing rich text.
+\annotatedlist richtext-processing
+*/
+/*!
+\page richtext-structure.html
+\contentspage richtext.html Contents
+\previouspage Rich Text Processing
+\nextpage The QTextCursor Interface
+\title Rich Text Document Structure
+\tableofcontents
+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
+\l{richtext-cursor.html}{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.
+\table
+\row
+\i \inlineimage richtext-document.png
+\i \bold{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.
+\endtable
+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
+\l{richtext-cursor.html}{The QTextCursor Interface}.
+\section1 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:
+\snippet doc/src/snippets/code/doc_src_richtext.qdoc 0
+Alternatively, they can be extracted from an existing editor:
+\snippet doc/src/snippets/code/doc_src_richtext.qdoc 1
+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 \l{richtext-cursor.html}{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:
+\snippet doc/src/snippets/textdocument-frames/xmlwriter.h 0
+\snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 0
+When navigating the document structure, it is useful to begin at the
+root frame because it provides access to the entire document structure.
+\section1 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.
+\section2 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:
+\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 3
+\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 5
+\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 6
+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:
+\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 0
+\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 1
+\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 2
+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: \l{QTextBlock::operator==()}{operator==()} and
+\l{QTextBlock::operator!=()}{operator!=()} are used to test whether two
+blocks are the same, and \l{QTextBlock::operator<()}{operator<()} is used
+to determine which one occurs first in a document.
+\section2 Frames
+Frames are provided by the QTextFrame class.
+Text frames group together blocks of text and child frames, creating
+document structures that are larger than paragraphs. The format of a frame
+specifies how it is rendered and positioned on the page. Frames are
+either inserted into the text flow, or they float on the left or right
+hand side of the page.
+Each document contains a root frame that contains all the other document
+elements. As a result, all frames except the root frame have a parent
+frame.
+Since text blocks are used to separate other document elements, each
+frame will always contain at least one text block, and zero or more
+child frames. We can inspect the contents of a frame by using a
+QTextFrame::iterator to traverse the frame's child elements:
+\snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 1
+\snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 2
+Note that the iterator selects both frames and blocks, so it is necessary
+to check which it is referring to. This allows us to navigate the document
+structure on a frame-by-frame basis yet still access text blocks if
+required. Both the QTextBlock::iterator and QTextFrame::iterator classes
+can be used in complementary ways to extract the required structure from
+a document.
+\section2 Tables
+Tables are provided by the QTextTable class.
+Tables are collections of cells that are arranged in rows and columns.
+Each table cell is a document element with its own character format, but it
+can also contain other elements, such as frames and text blocks. Table cells
+are automatically created when the table is constructed, or when extra rows
+or columns are added. They can also be moved between tables.
+QTextTable is a subclass of QTextFrame, so tables are treated like frames
+in the document structure. For each frame that we encounter in the
+document, we can test whether it represents a table, and deal with it in a
+different way:
+\snippet doc/src/snippets/textdocument-tables/xmlwriter.cpp 0
+\snippet doc/src/snippets/textdocument-tables/xmlwriter.cpp 1
+The cells within an existing table can be examined by iterating through
+the rows and columns.
+\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 9
+\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 10
+\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 11
+\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 12
+\section2 Lists
+Lists are provided by the QTextList class.
+Lists are sequences of text blocks that are formatted in the usual way, but
+which also provide the standard list decorations such as bullet points and
+enumerated items. Lists can be nested, and will be indented if the list's
+format specifies a non-zero indentation.
+We can refer to each list item by its index in the list:
+\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 0
+\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 1
+\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 2
+Since QTextList is a subclass of QTextBlockGroup, it does not group the
+list items as child elements, but instead provides various functions for
+managing them. This means that any text block we find when traversing a
+document may actually be a list item. We can ensure that list items are
+correctly identified by using the following code:
+\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 3
+\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 4
+\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 5
+\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 6
+\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 7
+\section2 Images
+Images in QTextDocument are represented by text fragments that reference
+external images via the resource mechanism. Images are created using the
+cursor interface, and can be modified later by changing the character
+format of the image's text fragment:
+\snippet doc/src/snippets/textdocument-imageformat/main.cpp 0
+\snippet doc/src/snippets/textdocument-imageformat/main.cpp 1
+\snippet doc/src/snippets/textdocument-imageformat/main.cpp 2
+The fragment that represents the image can be found by iterating over
+the fragments in the text block that contains the image.
+*/
+/*!
+\page richtext-cursor.html
+\contentspage richtext.html Contents
+\previouspage Rich Text Document Structure
+\nextpage Document Layouts
+\title The QTextCursor Interface
+\tableofcontents
+Documents can be edited via the interface provided by the QTextCursor
+class; cursors are either created using a constructor or obtained from
+an editor widget. The cursor is used to perform editing operations that
+correspond exactly to those the user is able to make themselves in an
+editor. As a result, information about the document structure is also
+available through the cursor, and this allows the structure to be
+modified. The use of a cursor-oriented interface for editing makes the
+process of writing a custom editor simpler for developers, since the
+editing operations can be easily visualized.
+The QTextCursor class also maintains information about any text it
+has selected in the document, again following a model that is
+conceptually similar to the actions made by the user to select text
+in an editor.
+Rich text documents can have multiple cursors
+associated with them, and each of these contains information about their
+position in the document and any selections that they may hold. This
+cursor-based paradigm makes common operations, such as cutting and pasting
+text, simple to implement programmatically, yet it also allows more complex
+editing operations to be performed on the document.
+This chapter describes most of the common editing operations that you
+will need to perform using a cursor, from basic insertion of text and
+document elements to more complex manipulation of document structures.
+\section1 Cursor-Based Editing
+At the simplest level, text documents are made up of a string of characters,
+marked up in some way to represent the block structure of the text within the
+document. QTextCursor provides a cursor-based interface that allows the
+contents of a QTextDocument to be manipulated at the character level. Since
+the elements (blocks, frames, tables, etc.) are also encoded in the character
+stream, the document structure can itself be changed by the cursor.
+The cursor keeps track of its location within its parent document, and can
+report information about the surrounding structure, such as the enclosing
+text block, frame, table, or list. The formats of the enclosing structures
+can also be directly obtained through the cursor.
+\section2 Using a Cursor
+The main use of a cursor is to insert or modify text within a block.
+We can use a text editor's cursor to do this:
+\snippet doc/src/snippets/textblock-formats/main.cpp 0
+Alternatively, we can obtain a cursor directly from a document:
+\snippet doc/src/snippets/textdocument-images/main.cpp 0
+The cursor is positioned at the start of the document so that we can write
+into the first (empty) block in the document.
+\section2 Grouping Cursor Operations
+A series of editing operations can be packaged together so that they can
+be replayed, or undone together in a single action. This is achieved by
+using the \c beginEditBlock() and \c endEditBlock() functions in the
+following way, as in the following example where we select the word that
+contains the cursor:
+\snippet doc/src/snippets/textdocument-selections/mainwindow.cpp 0
+If editing operations are not grouped, the document automatically records
+the individual operations so that they can be undone later. Grouping
+operations into larger packages can make editing more efficient both for
+the user and for the application, but care has to be taken not to group too
+many operations together as the user may want find-grained control over the
+undo process.
+\section2 Multiple Cursors
+Multiple cursors can be used to simultaneously edit the same document,
+although only one will be visible to the user in a QTextEdit widget.
+The QTextDocument ensures that each cursor writes text correctly and
+does not interfere with any of the others.
+\omit
+\snippet doc/src/snippets/textdocument-cursors/main.cpp 0
+\snippet doc/src/snippets/textdocument-cursors/main.cpp 1
+\endomit
+\section1 Inserting Document Elements
+QTextCursor provides several functions that can be used to change the
+structure of a rich text document. Generally, these functions allow
+document elements to be created with relevant formatting information,
+and they are inserted into the document at the cursor's position.
+The first group of functions insert block-level elements, and update the
+cursor position, but they do not return the element that was inserted:
+\list
+\i \l{QTextCursor::insertBlock()}{insertBlock()} inserts a new text block
+(paragraph) into a document at the cursor's position, and moves the
+cursor to the start of the new block.
+\i \l{QTextCursor::insertFragment()}{insertFragment()} inserts an existing
+text fragment into a document at the cursor's position.
+\i \l{QTextCursor::insertImage()}{insertImage()} inserts an image into a
+document at the cursor's position.
+\i \l{QTextCursor::insertText()}{insertText()} inserts text into the
+document at the cursor's position.
+\endlist
+You can examine the contents of the element that was inserted through the
+cursor interface.
+The second group of functions insert elements that provide structure to
+the document, and return the structure that was inserted:
+\list
+\i \l{QTextCursor::insertFrame()}{insertFrame()} inserts a frame into the
+document \e after the cursor's current block, and moves the cursor to
+the start of the empty block in the new frame.
+\i \l{QTextCursor::insertList()}{insertList()} inserts a list into the
+document at the cursor's position, and moves the cursor to the start
+of the first item in the list.
+\i \l{QTextCursor::insertTable()}{insertTable()} inserts a table into
+the document \e after the cursor's current block, and moves the cursor
+to the start of the block following the table.
+\endlist
+These elements either contain or group together other elements in the
+document.
+\section2 Text and Text Fragments
+Text can be inserted into the current block in the current character
+format, or in a custom format that is specified with the text:
+\snippet doc/src/snippets/textdocument-charformats/main.cpp 0
+Once the character format has been used with a cursor, that format becomes
+the default format for any text inserted with that cursor until another
+character format is specified.
+If a cursor is used to insert text without specifying a character format,
+the text will be given the character format used at that position in the
+document.
+\section2 Blocks
+Text blocks are inserted into the document with the
+\l{QTextCursor::insertBlock()}{insertBlock()} function.
+\snippet doc/src/snippets/textblock-formats/main.cpp 1
+The cursor is positioned at the start of the new block.
+\section2 Frames
+Frames are inserted into a document using the cursor, and will be placed
+within the cursor's current frame \e after the current block.
+The following code shows how a frame can be inserted between two text
+blocks in a document's root frame. We begin by finding the cursor's
+current frame:
+\snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 0
+We insert some text in this frame then set up a frame format for the
+child frame:
+\snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 1
+The frame format will give the frame an external margin of 32 pixels,
+internal padding of 8 pixels, and a border that is 4 pixels wide.
+See the QTextFrameFormat documentation for more information about
+frame formats.
+The frame is inserted into the document after the preceding text:
+\snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 2
+We add some text to the document immediately after we insert the frame.
+Since the text cursor is positioned \e{inside the frame} when it is inserted
+into the document, this text will also be inserted inside the frame.
+Finally, we position the cursor outside the frame by taking the last
+available cursor position inside the frame we recorded earlier:
+\snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 3
+The text that we add last is inserted after the child frame in the
+document. Since each frame is padded with text blocks, this ensures that
+more elements can always be inserted with a cursor.
+\section2 Tables
+Tables are inserted into the document using the cursor, and will be
+placed within the cursor's current frame \e after the current block:
+\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 0
+\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 3
+Tables can be created with a specific format that defines the overall
+properties of the table, such as its alignment, background color, and
+the cell spacing used. It can also determine the constraints on each
+column, allowing each of them to have a fixed width, or resize according
+to the available space.
+\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 2
+The columns in the table created above will each take up a certain
+percentage of the available width. Note that the table format is
+optional; if you insert a table without a format, some sensible
+default values will be used for the table's properties.
+Since cells can contain other document elements, they too can be
+formatted and styled as necessary.
+Text can be added to the table by navigating to each cell with the cursor
+and inserting text.
+\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 4
+We can create a simple timetable by following this approach:
+\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 5
+\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 6
+\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 7
+\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 8
+\section2 Lists
+Lists of block elements can be automatically created and inserted into the
+document at the current cursor position. Each list that is created in this
+way requires a list format to be specified:
+\snippet doc/src/snippets/textdocument-lists/mainwindow.cpp 0
+The above code first checks whether the cursor is within an existing list
+and, if so, gives the list format for the new list a suitable level of
+indentation. This allows nested lists to be created with increasing
+levels of indentation. A more sophisticated implementation would also use
+different kinds of symbol for the bullet points in each level of the list.
+\section2 Images
+Inline images are added to documents through the cursor in the usual manner.
+Unlike many other elements, all of the image properties are specified by the
+image's format. This means that a QTextImageFormat object has to be
+created before an image can be inserted:
+\snippet doc/src/snippets/textdocument-images/main.cpp 1
+The image name refers to an entry in the application's resource file.
+The method used to derive this name is described in
+\l{resources.html}{The Qt Resource System}.
+\section1 Examples
+Rich text is stored in text documents that can either be created by
+importing HTML from an external source, or generated using a QTextCursor.
+\section2 Manipulating Rich Text
+The easiest way to use a rich text document is through
+the QTextEdit class, providing an editable view onto a document. The code
+below imports HTML into a document, and displays the document using a
+text edit widget.
+\snippet doc/src/snippets/scribe-overview/main.cpp 1
+You can retrieve the document from the text edit using the
+document() function. The document can then be edited programmatically
+using the QTextCursor class. This class is modeled after a screen
+cursor, and editing operations follow the same semantics. The following
+code changes the first line of the document to a bold font, leaving all
+other font properties untouched. The editor will be automatically
+updated to reflect the changes made to the underlying document data.
+\snippet doc/src/snippets/scribe-overview/main.cpp 0
+Note that the cursor was moved from the start of the first line to the
+end, but that it retained an anchor at the start of the line. This
+demonstrates the cursor-based selection facilities of the
+QTextCursor class.
+\section2 Generating a Calendar
+Rich text can be generated very quickly using the cursor-based
+approach. The following example shows a simple calendar in a
+QTextEdit widget with bold headers for the days of the week:
+\snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 0
+\codeline
+\snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 1
+\snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 2
+\snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 3
+The above example demonstrates how simple it is to quickly generate new
+rich text documents using a minimum amount of code. Although we have
+generated a crude fixed-pitch calendar to avoid quoting too much code,
+Scribe provides much more sophisticated layout and formatting features.
+*/
+/*!
+\page richtext-layouts.html
+\contentspage richtext.html Contents
+\previouspage The QTextCursor Interface
+\nextpage Common Rich Text Editing Tasks
+\title Document Layouts
+\tableofcontents
+The layout of a document is only relevant when it is to be displayed on
+a device, or when some information is requested that requires a visual
+representation of the document. Until this occurs, the document does
+not need to be formatted and prepared for a device.
+\section1 Overview
+Each document's layout is managed by a subclass of the
+QAbstractTextDocumentLayout class. This class provides a common
+interface for layout and rendering engines. The default rendering
+behavior is currently implemented in a private class. This approach
+makes it possible to create custom layouts, and provides the
+mechanism used when preparing pages for printing or exporting to
+Portable Document Format (PDF) files.
+\section1 Example - Shaped Text Layout
+Sometimes it is important to be able to format plain text within an
+irregularly-shaped region, perhaps when rendering a custom widget, for
+example. Scribe provides generic features, such as those provided by
+the QTextLayout class, to help developers perform word-wrapping and
+layout tasks without the need to create a document first.
+\img plaintext-layout.png
+Formatting and drawing a paragraph of plain text is straightforward.
+The example below will lay out a paragraph of text, using a single
+font, around the right hand edge of a circle.
+\snippet doc/src/snippets/plaintextlayout/window.cpp 0
+We create a text layout, specifying the text string we want to display
+and the font to use. We ensure that the text we supplied is formatted
+correctly by obtaining text lines from the text format, and wrapping
+the remaining text using the available space. The lines are positioned
+as we move down the page.
+The formatted text can be drawn onto a paint device; in the above code,
+the text is drawn directly onto a widget.
+*/
+/*!
+\page richtext-common-tasks.html
+\contentspage richtext.html Contents
+\previouspage Document Layouts
+\nextpage Advanced Rich Text Processing
+\title Common Rich Text Editing Tasks
+\tableofcontents
+There are a number of tasks that are often performed by developers
+when editing and processing text documents using Qt. These include the use
+of display widgets such as QTextBrowser and QTextEdit, creation of
+documents with QTextDocument, editing using a QTextCursor, and
+exporting the document structure.
+This document outlines some of the more common ways of using the rich
+text classes to perform these tasks, showing convenient patterns that can
+be reused in your own applications.
+\section1 Using QTextEdit
+A text editor widget can be constructed and used to display HTML in the
+following way:
+\snippet doc/src/snippets/code/doc_src_richtext.qdoc 2
+By default, the text editor contains a document with a root frame, inside
+which is an empty text block. This document can be obtained so that it can
+be modified directly by the application:
+\snippet doc/src/snippets/code/doc_src_richtext.qdoc 3
+The text editor's cursor may also be used to edit a document:
+\snippet doc/src/snippets/code/doc_src_richtext.qdoc 4
+Although a document can be edited using many cursors at once, a QTextEdit
+only displays a single cursor at a time. Therefore, if we want to update the
+editor to display a particular cursor or its selection, we need to set the
+editor's cursor after we have modified the document:
+\snippet doc/src/snippets/code/doc_src_richtext.qdoc 5
+\section1 Selecting Text
+Text is selected by moving the cursor using operations that are similar to
+those performed by a user in a text editor. To select text between two
+points in the document, we need to position the cursor at the first point
+then move it using a special mode (\l{QTextCursor::MoveMode}) with a
+move operation (\l{QTextCursor::MoveOperation}).
+When we select the text, we leave the selection anchor at the old cursor
+position just as the user might do by holding down the Shift key when
+selecting text:
+\snippet doc/src/snippets/textdocument-selections/mainwindow.cpp 1
+In the above code, a whole word is selected using this method. QTextCursor
+provides a number of common move operations for selecting individual
+characters, words, lines, and whole blocks.
+\section1 Finding Text
+QTextDocument provides a cursor-based interface for searching, making
+it easy to find and modify text in the style of a text editor. The following
+code finds all the instances of a particular word in a document, and changes
+the color of each:
+\snippet doc/src/snippets/textdocument-find/main.cpp 0
+\snippet doc/src/snippets/textdocument-find/main.cpp 1
+Note that the cursor does not have to be moved after each search and replace
+operation; it is always positioned at the end of the word that was just
+replaced.
+\section1 Printing Documents
+QTextEdit is designed for the display of large rich text documents that are
+read on screen, rendering them in the same way as a web browser. As a result,
+it does not automatically break the contents of the document into page-sized
+pieces that are suitable for printing.
+QTextDocument provides a \l{QTextDocument::print()}{print()} function to
+allow documents to be printed using the QPrinter class. The following code
+shows how to prepare a document in a QTextEdit for printing with a QPrinter:
+\snippet doc/src/snippets/textdocument-printing/mainwindow.cpp 0
+The document is obtained from the text editor, and a QPrinter is constructed
+then configured using a QPrintDialog. If the user accepts the printer's
+configuration then the document is formatted and printed using the
+\l{QTextDocument::print()}{print()} function.
+*/
+/*!
+\page richtext-advanced-processing.html
+\contentspage richtext.html Contents
+\previouspage Common Rich Text Editing Tasks
+\nextpage Supported HTML Subset
+\title Advanced Rich Text Processing
+\section1 Handling Large Files
+Qt does not limit the size of files that are used for text
+processing.  In most cases, this will not present a problem. For
+especially large files, however, you might experience that your
+application will become unresponsive or that you will run out of
+memory. The size of the files you can load depends on your
+hardware and on Qt's and your own application's implementation.
+If you are faced with this problem, we recommend that you address the
+following issues:
+\list
+\o You should consider breaking up large paragraphs into smaller
+ones as Qt handles small paragraphs better. You could also
+insert line breaks at regular intervals, which will look the
+same as one large paragraph in a QTextEdit.
+\o You can reduce the amount of blocks in a QTextDocument with
+\l{QTextDocument::}{maximumBlockCount()}. The document is only
+as large as the number of blocks as far as QTextEdit is concerned.
+\o When adding text to a text edit, it is an advantage to add it
+in an edit block (see example below). The result is that the
+text edit does not need to build the entire document structure at once.
+\endlist
+We give an example of the latter technique from the list. We assume that
+the text edit is visible.
+\snippet doc/src/snippets/code/doc_src_richtext.qdoc 6
+\omit
+Ideas for other sections:
+* Hiding QTextBlock elements.
+* Changing the word wrapping mode in QTextEdit. Custom word wrapping?
+\endomit
+*/
+/*!
+\page richtext-html-subset.html
+\title Supported HTML Subset
+\brief Describes the support for HTML markup in text widgets.
+\contentspage richtext.html Contents
+\previouspage Common Rich Text Editing Tasks
+Qt's text widgets are able to display rich text, specified using a subset of \l{HTML 4}
+markup. Widgets that use QTextDocument, such as QLabel and QTextEdit, are able to display
+rich text specified in this way.
+\tableofcontents
+\section1 Using HTML Markup in Text Widgets
+Widgets automatically detect HTML markup and display rich text accordingly. For example,
+setting a label's \l{QLabel::}{text} property with the string \c{"<b>Hello</b> <i>Qt!</i>"}
+will result in the label displaying text like this: \bold{Hello} \e{Qt!}
+When HTML markup is used for text, Qt follows the rules defined by the \l{HTML 4}
+specification. This includes default properties for text layout, such as the
+direction of the text flow (left-to-right) which can be changed by applying the
+\l{#Block Attributes}{\c dir} attribute to blocks of text.
+\section1 Supported Tags
+The following table lists the HTML tags supported by Qt's
+\l{Rich Text Processing}{rich text} engine:
+\table
+\header \o Tag
+\o Description
+\o Comment
+\row    \o \c a
+\o Anchor or link
+\o Supports the \c href and \c name attributes.
+\row    \o \c address
+\o Address
+\o
+\row    \o \c b
+\o Bold
+\o
+\row    \o \c big
+\o Larger font
+\o
+\row    \o \c blockquote
+\o Indented paragraph
+\o
+\row    \o \c body
+\o Document body
+\o Supports the \c bgcolor attribute, which
+can be a Qt \l{QColor::setNamedColor()}{color name}
+or a \c #RRGGBB color specification.
+\row    \o \c br
+\o Line break
+\o
+\row    \o \c center
+\o Centered paragraph
+\o
+\row    \o \c cite
+\o Inline citation
+\o Same as \c i.
+\row    \o \c code
+\o Code
+\o Same as \c tt.
+\row    \o \c dd
+\o Definition data
+\o
+\row    \o \c dfn
+\o Definition
+\o Same as \c i.
+\row    \o \c div
+\o Document division
+\o Supports the standard \l{block attributes}.
+\row    \o \c dl
+\o Definition list
+\o Supports the standard \l{block attributes}.
+\row    \o \c dt
+\o Definition term
+\o Supports the standard \l{block attributes}.
+\row    \o \c em
+\o Emphasized
+\o Same as \c i.
+\row    \o \c font
+\o Font size, family, and/or color
+\o Supports the following attributes:
+\c size, \c face, and \c color (Qt
+\l{QColor::setNamedColor()}{color names} or
+\c #RRGGBB).
+\row    \o \c h1
+\o Level 1 heading
+\o Supports the standard \l{block attributes}.
+\row    \o \c h2
+\o Level 2 heading
+\o Supports the standard \l{block attributes}.
+\row    \o \c h3
+\o Level 3 heading
+\o Supports the standard \l{block attributes}.
+\row    \o \c h4
+\o Level 4 heading
+\o Supports the standard \l{block attributes}.
+\row    \o \c h5
+\o Level 5 heading
+\o Supports the standard \l{block attributes}.
+\row    \o \c h6
+\o Level 6 heading
+\o Supports the standard \l{block attributes}.
+\row    \o \c head
+\o Document header
+\o
+\row    \o \c hr
+\o Horizontal line
+\o Supports the \c width attribute, which can
+be specified as an absolute or relative (\c %) value.
+\row    \o \c html
+\o HTML document
+\o
+\row    \o \c i
+\o Italic
+\o
+\row    \o \c img
+\o Image
+\o Supports the \c src, \c source
+(for Qt 3 compatibility), \c width, and \c height
+attributes.
+\row    \o \c kbd
+\o User-entered text
+\o
+\row    \o \c meta
+\o Meta-information
+\o If a text encoding is specified using the \c{meta} tag,
+it is picked up by Qt::codecForHtml().
+Likewise, if an encoding is specified to
+QTextDocument::toHtml(), the encoding is stored using
+a \c meta tag, for example:
+\snippet doc/src/snippets/code/doc_src_richtext.qdoc 7
+\row    \o \c li
+\o List item
+\o
+\row    \o \c nobr
+\o Non-breakable text
+\o
+\row    \o \c ol
+\o Ordered list
+\o Supports the standard \l{list attributes}.
+\row    \o \c p
+\o Paragraph
+\o Left-aligned by default. Supports the standard
+\l{block attributes}.
+\row    \o \c pre
+\o Preformated text
+\o
+\row    \o \c qt
+\o Qt rich-text document
+\o Synonym for \c html. Provided for compatibility with
+earlier versions of Qt.
+\row    \o \c s
+\o Strikethrough
+\o
+\row    \o \c samp
+\o Sample code
+\o Same as \c tt.
+\row    \o \c small
+\o Small font
+\o
+\row    \o \c span
+\o Grouped elements
+\o
+\row    \o \c strong
+\o Strong
+\o Same as \c b.
+\row    \o \c sub
+\o Subscript
+\o
+\row    \o \c sup
+\o Superscript
+\o
+\row    \o \c table
+\o Table
+\o Supports the following attributes: \c border,
+\c bgcolor (Qt \l{QColor::setNamedColor()}{color names}
+or \c #RRGGBB), \c cellspacing, \c cellpadding,
+\c width (absolute or relative), and \c height.
+\row    \o \c tbody
+\o Table body
+\o Does nothing.
+\row    \o \c td
+\o Table data cell
+\o Supports the standard \l{table cell attributes}.
+\row    \o \c tfoot
+\o Table footer
+\o Does nothing.
+\row    \o \c th
+\o Table header cell
+\o Supports the standard \l{table cell attributes}.
+\row    \o \c thead
+\o Table header
+\o If the \c thead tag is specified, it is used when printing tables
+that span multiple pages.
+\row    \o \c title
+\o Document title
+\o The value specified using the \c
+title tag is available through
+QTextDocument::metaInformation().
+\row    \o \c tr
+\o Table row
+\o Supports the \c bgcolor attribute, which
+can be a Qt \l{QColor::setNamedColor()}{color name}
+or a \c #RRGGBB color specification.
+\row    \o \c tt
+\o Typewrite font
+\o
+\row    \o \c u
+\o Underlined
+\o
+\row    \o \c ul
+\o Unordered list
+\o Supports the standard \l{list attributes}.
+\row    \o \c var
+\o Variable
+\o Same as \c i.
+\endtable
+\section1 Block Attributes
+The following attributes are supported by the \c div, \c dl, \c
+dt, \c h1, \c h2, \c h3, \c h4, \c h5, \c h6, \c p tags:
+\list
+\o \c align (\c left, \c right, \c center, \c justify)
+\o \c dir (\c ltr, \c rtl)
+\endlist
+\section1 List Attributes
+The following attribute is supported by the \c ol and \c ul tags:
+\list
+\o \c type (\c 1, \c a, \c A, \c square, \c disc, \c circle)
+\endlist
+\section1 Table Cell Attributes
+The following attributes are supported by the \c td and \c th
+tags:
+\list
+\o \c width (absolute, relative, or no-value)
+\o \c bgcolor (Qt \l{QColor::setNamedColor()}{color names} or \c #RRGGBB)
+\o \c colspan
+\o \c rowspan
+\o \c align (\c left, \c right, \c center, \c justify)
+\o \c valign (\c top, \c middle, \c bottom)
+\endlist
+\section1 CSS Properties
+The following table lists the CSS properties supported by Qt's
+\l{Rich Text Processing}{rich text} engine:
+\table
+\header \o Property
+\o Values
+\o Description
+\row
+\o \c background-color
+\o <color>
+\o Background color for elements
+\row
+\o \c background-image
+\o <uri>
+\o Background image for elements
+\row    \o \c color
+\o <color>
+\o Text foreground color
+\row    \o \c font-family
+\o <family name>
+\o Font family name
+\row    \o \c font-size
+\o [ small | medium | large | x-large | xx-large ] | <size>pt | <size>px
+\o Font size relative to the document font, or specified in points or pixels
+\row    \o \c font-style
+\o [ normal | italic | oblique ]
+\o
+\row    \o \c font-weight
+\o [ normal | bold | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 ]
+\o Specifies the font weight used for text, where \c normal and \c bold
+are mapped to the corresponding QFont weights. Numeric values are
+8 times the equivalent QFont weight values.
+\row    \o \c text-decoration
+\o none | [ underline || overline || line-through ]
+\o Additional text effects
+\row    \o \c font
+\o [ [ <'font-style'> || <'font-weight'> ]? <'font-size'> <'font-family'> ]
+\o Font shorthand property
+\row    \o \c text-indent
+\o <length>px
+\o First line text indentation in pixels
+\row    \o \c white-space
+\o normal | pre | nowrap | pre-wrap
+\o Declares how whitespace in HTML is handled.
+\row    \o \c margin-top
+\o <length>px
+\o Top paragraph margin in pixels
+\row    \o \c margin-bottom
+\o <length>px
+\o Bottom paragraph margin in pixels
+\row    \o \c margin-left
+\o <length>px
+\o Left paragraph margin in pixels
+\row    \o \c margin-right
+\o <length>px
+\o Right paragraph margin in pixels
+\row    \o \c padding-top
+\o <length>px
+\o Top table cell padding in pixels
+\row    \o \c padding-bottom
+\o <length>px
+\o Bottom table cell padding in pixels
+\row    \o \c padding-left
+\o <length>px
+\o Left table cell padding in pixels
+\row    \o \c padding-right
+\o <length>px
+\o Right table cell padding in pixels
+\row    \o \c padding
+\o <length>px
+\o Shorthand for setting all the padding properties at once.
+\row    \o \c vertical-align
+\o baseline | sub | super | middle | top | bottom
+\o Vertical text alignment. For vertical alignment in text table cells only middle, top, and bottom apply.
+\row    \o \c border-color
+\o <color>
+\o Border color for text tables.
+\row    \o \c border-style
+\o none | dotted | dashed | dot-dash | dot-dot-dash | solid | double | groove | ridge | inset | outset
+\o Border style for text tables.
+\row    \o \c background
+\o [ <'background-color'> || <'background-image'> ]
+\o Background shorthand property
+\row    \o \c page-break-before
+\o [ auto | always ]
+\o Make it possible to enforce a page break before the paragraph/table
+\row    \o \c page-break-after
+\o [ auto | always ]
+\o Make it possible to enforce a page break after the paragraph/table
+\row    \o float
+\o [ left | right | none ]
+\o Specifies where an image or a text will be placed in another element. Note that the \c float property is
+only supported for tables and images.
+\row    \o \c text-transform
+\o [ uppercase | lowercase ]
+\o Select the transformation that will be performed on the text prior to displaying it.
+\row    \o \c font-variant
+\o small-caps
+\o Perform the smallcaps transformation on the text prior to displaying it.
+\row    \o \c word-spacing
+\o <width>px
+\o Specifies an alternate spacing between each word.
+\endtable
+\section1 Supported CSS Selectors
+All CSS 2.1 selector classes are supported except pseudo-class selectors such
+as \c{:first-child}, \c{:visited} and \c{:hover}.
+*/