source: trunk/src/gui/text/qabstracttextdocumentlayout.cpp@ 858

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the QtGui module 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.1, 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 have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

#include <qabstracttextdocumentlayout.h>
#include <qtextformat.h>
#include "qtextdocument_p.h"
#include "qtextengine_p.h"

#include "qabstracttextdocumentlayout_p.h"

QT_BEGIN_NAMESPACE

/*!
    \class QAbstractTextDocumentLayout
    \reentrant

    \brief The QAbstractTextDocumentLayout class is an abstract base
    class used to implement custom layouts for QTextDocuments.

    \ingroup richtext-processing

    The standard layout provided by Qt can handle simple word processing
    including inline images, lists and tables.

    Some applications, e.g., a word processor or a DTP application might need
    more features than the ones provided by Qt's layout engine, in which case
    you can subclass QAbstractTextDocumentLayout to provide custom layout
    behavior for your text documents.

    An instance of the QAbstractTextDocumentLayout subclass can be installed
    on a QTextDocument object with the
    \l{QTextDocument::}{setDocumentLayout()} function.

    You can insert custom objects into a QTextDocument; see the
    QTextObjectInterface class description for details.

    \sa QTextObjectInterface
*/

/*!
    \class QTextObjectInterface
    \brief The QTextObjectInterface class allows drawing of
           custom text objects in \l{QTextDocument}s.
    \since 4.5

    A text object describes the structure of one or more elements in a
    text document; for instance, images imported from HTML are
    implemented using text objects. A text object knows how to lay out
    and draw its elements when a document is being rendered.

    Qt allows custom text objects to be inserted into a document by
    registering a custom \l{QTextCharFormat::objectType()}{object
    type} with QTextCharFormat. A QTextObjectInterface must also be
    implemented for this type and be
    \l{QAbstractTextDocumentLayout::registerHandler()}{registered}
    with the QAbstractTextDocumentLayout of the document. When the
    object type is encountered while rendering a QTextDocument, the
    intrinsicSize() and drawObject() functions of the interface are
    called.

    The following list explains the required steps of inserting a
    custom text object into a document:

    \list
        \o Choose an \a objectType. The \a objectType is an integer with a
            value greater or equal to QTextFormat::UserObject.
         \o Create a QTextCharFormat object and set the object type to the
            chosen type using the setObjectType() function.
         \o Implement the QTextObjectInterface class.
         \o Call QAbstractTextDocumentLayout::registerHandler() with an instance of your
            QTextObjectInterface subclass to register your object type.
         \o Insert QChar::ObjectReplacementCharacter with the aforementioned
            QTextCharFormat of the chosen object type into the document.
            As mentioned, the functions of QTextObjectInterface
            \l{QTextObjectInterface::}{intrinsicSize()} and
            \l{QTextObjectInterface::}{drawObject()} will then be called with the
            QTextFormat as parameter whenever the replacement character is
            encountered.
    \endlist

    A class implementing a text object needs to inherit both QObject
    and QTextObjectInterface. QObject must be the first class
    inherited. For instance:

    \snippet examples/richtext/textobject/svgtextobject.h 1

    The data of a text object is usually stored in the QTextCharFormat
    using QTextCharFormat::setProperty(), and then retrieved with
    QTextCharFormat::property().

    \warning Copy and Paste operations ignore custom text objects.

    \sa {Text Object Example}, QTextCharFormat, QTextLayout
*/

/*!
    \fn QTextObjectInterface::~QTextObjectInterface()

    Destroys this QTextObjectInterface.
*/

/*!
    \fn virtual QSizeF QTextObjectInterface::intrinsicSize(QTextDocument *doc, int posInDocument, const QTextFormat &format) = 0

    The intrinsicSize() function returns the size of the text object
    represented by \a format in the given document (\a doc) at the
    given position (\a posInDocument).

    The size calculated will be used for subsequent calls to
    drawObject() for this \a format.

    \sa drawObject()
*/

/*!
    \fn virtual void QTextObjectInterface::drawObject(QPainter *painter, const QRectF &rect, QTextDocument *doc, int posInDocument, const QTextFormat &format) = 0

    Draws this text object using the specified \a painter.

    The size of the rectangle, \a rect, to draw in is the size
    previously calculated by intrinsicSize(). The rectangles position
    is relative to the \a painter.

    You also get the document (\a doc) and the position (\a
    posInDocument) of the \a format in that document.

    \sa intrinsicSize()
*/

/*!
    \fn void QAbstractTextDocumentLayout::update(const QRectF &rect)

    This signal is emitted when the rectangle \a rect has been updated.

    Subclasses of QAbstractTextDocumentLayout should emit this signal when
    the layout of the contents change in order to repaint.
*/

/*!
   \fn void QAbstractTextDocumentLayout::updateBlock(const QTextBlock &block)
   \since 4.4

   This signal is emitted when the specified \a block has been updated.

   Subclasses of QAbstractTextDocumentLayout should emit this signal when
   the layout of \a block has changed in order to repaint. 
*/

/*!
    \fn void QAbstractTextDocumentLayout::documentSizeChanged(const QSizeF &newSize)

    This signal is emitted when the size of the document layout changes to
    \a newSize.

    Subclasses of QAbstractTextDocumentLayout should emit this signal when the
    document's entire layout size changes. This signal is useful for widgets
    that display text documents since it enables them to update their scroll
    bars correctly.

    \sa documentSize()
*/

/*!
    \fn void QAbstractTextDocumentLayout::pageCountChanged(int newPages)

    This signal is emitted when the number of pages in the layout changes;
    \a newPages is the updated page count.

    Subclasses of QAbstractTextDocumentLayout should emit this signal when
    the number of pages in the layout has changed. Changes to the page count
    are caused by changes to the layout or the document content itself.

    \sa pageCount()
*/

/*!
    \fn int QAbstractTextDocumentLayout::pageCount() const

    Returns the number of pages contained in the layout.

    \sa pageCountChanged()
*/

/*!
    \fn QSizeF QAbstractTextDocumentLayout::documentSize() const

    Returns the total size of the document's layout.

    This information can be used by display widgets to update their scroll bars
    correctly.

    \sa documentSizeChanged(), QTextDocument::pageSize
*/

/*!
    \fn void QAbstractTextDocumentLayout::draw(QPainter *painter, const PaintContext &context)

    Draws the layout with the given \a painter using the given \a context.
*/

/*!
    \fn int QAbstractTextDocumentLayout::hitTest(const QPointF &point, Qt::HitTestAccuracy accuracy) const

    Returns the cursor postion for the given \a point with the specified
    \a accuracy. Returns -1 if no valid cursor position was found.
*/

/*!