/****************************************************************************

**

** 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: