source: trunk/doc/src/richtext.qdoc@ 357

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page richtext.html
\nextpage Rich Text Document Structure

\title Rich Text Processing
\ingroup architecture
\ingroup text-processing
\brief An overview of Qt's rich text processing, editing and display features.

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

See also the list of \l{Text Processing Classes}.

*/

/*!
\page richtext-structure.html
\contentspage richtext.html Contents
\previouspage Rich Text Processing
\nextpage The QTextCursor Interface

\title Rich Text Document Structure

\tableofcontents

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 for use with a QTextEdit widget or in a custom editor.
Although QTextEdit makes it easy to display and edit rich text, documents
can also be used independently of any editor widget, for example: