source: trunk/doc/src/examples/textobject.qdoc@ 560

/****************************************************************************
**
** 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$
**
****************************************************************************/

/*!
    \example richtext/textobject
    \title Text Object Example
    
    The Text Object example shows how to insert an SVG file into a
    QTextDocument.

    \image textobject-example.png

    A QTextDocument consists of a hierarchy of elements, such as text blocks and
    frames. A text object describes the structure or format of one or more of these
    elements. For instance, images imported from HTML are implemented using text
    objects. Text objects are used by the document's
    \l{QAbstractTextDocumentLayout}{layout} to lay out and render (paint) the
    document. Each object knows how to paint the elements they govern, and
    calculates their size. 

    To be able to insert an SVG image into a text document, we create
    a text object, and implement painting for that object. This object
    can then be \l{QTextCharFormat::setObjectType()}{set} on a
    QTextCharFormat. We also register the text object with the layout
    of the document, enabling it to draw \l{QTextCharFormat}s governed
    by our text object. We can summarize the procedure with the
    following steps:

    \list
        \o Implement the text object.
        \o Register the text object with the layout of the text
           document.
        \o Set the text object on a QTextCharFormat.
        \o Insert a QChar::ObjectReplacementCharacter with that
           text char format into the document.
    \endlist

    The example consists of the following classes: