Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

1 files changed, 156 insertions, 0 deletions

diff --git a/doc/src/examples/textobject.qdoc b/doc/src/examples/textobject.qdoc
new file mode 100644
index 0000000..a2e3de0
--- /dev/null
+++ b/doc/src/examples/textobject.qdoc
@@ -0,0 +1,156 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 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:FDL$
+** 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 Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $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:
+
+    \list
+        \o \c{SvgTextObject} implements the text object.
+        \o \c{Window} shows a QTextEdit into which SVG images can be
+           inserted.
+    \endlist
+
+    \section1 SvgTextObject Class Definition
+
+    Let's take a look at the header file of \c {SvgTextObject}:
+
+    \snippet examples/richtext/textobject/svgtextobject.h 0
+
+    A text object is a QObject that implements QTextObjectInterface.
+    Note that the first class inherited must be QObject, and that
+    you must use Q_INTERFACES to let Qt know that your class
+    implements QTextObjectInterface.
+
+    The document layout keeps a collection of text objects stored as
+    \l{QObject}s, each of which has an associated object type. The
+    layout casts the QObject for the associated object type into the
+    QTextObjectInterface.
+
+    The \l{QTextObjectInterface::}{intrinsicSize()} and
+    \l{QTextObjectInterface::}{drawObject()} functions are then used
+    to calculate the size of the text object and draw it.
+
+    \section1 SvgTextObject Class Implementation
+
+    We start of by taking a look at the
+    \l{QTextObjectInterface::}{intrinsicSize()} function:
+
+    \snippet examples/richtext/textobject/svgtextobject.cpp 0
+
+    \c intrinsicSize() is called by the layout to calculate the size
+    of the text object. Notice that we have drawn the SVG image on a
+    QImage. This is because SVG rendering is quite expensive. The
+    example would lag seriously for large images if we drew them
+    with a QSvgRenderer each time.
+
+    \snippet examples/richtext/textobject/svgtextobject.cpp 1
+
+    In \c drawObject(), we paint the SVG image using the QPainter
+    provided by the layout.
+
+    \section1 Window Class Definition
+
+    The \c Window class is a self-contained window that has a
+    QTextEdit in which SVG images can be inserted.
+
+    \snippet examples/richtext/textobject/window.h 0
+
+    The \c insertTextObject() slot inserts an SVG image at the current
+    cursor position, while \c setupTextObject() creates and registers
+    the SvgTextObject with the layout of the text edit's document.
+
+    The constructor simply calls \c setupTextObject() and \c
+    setupGui(), which creates and lays out the widgets of the \c
+    Window.
+
+    \section1 Window Class Implementation
+
+    We will now take a closer look at the functions that are relevant
+    to our text object, starting with the \c setupTextObject()
+    function.
+    
+    \snippet examples/richtext/textobject/window.cpp 3
+
+    \c {SvgTextFormat}'s value is the number of our object type. It is
+    used to identify object types by the document layout. 
+
+    Note that we only create one SvgTextObject instance; it will be
+    used for all QTextCharFormat's with the \c SvgTextFormat object
+    type.
+
+    Let's move on to the \c insertTextObject() function:
+
+    \snippet examples/richtext/textobject/window.cpp 1
+
+    First, the \c .svg file is opened and its contents are read
+    into the \c svgData array. 
+
+    \snippet examples/richtext/textobject/window.cpp 2
+
+    To speed things up, we buffer the SVG image in a QImage.  We use
+    \l{QTextFormat::}{setProperty()} to store the QImage in the in the
+    QTextCharFormat. We can retrieve it later with
+    \l{QTextCharFormat::}{property()}.
+
+    We insert the char format in the standard way - using a
+    QTextCursor. Notice that we use the special QChar
+    \l{QChar::}{ObjectReplacementCharacter}.
+*/
+