diff options
Diffstat (limited to 'doc/src/examples/textobject.qdoc')
| -rw-r--r-- | doc/src/examples/textobject.qdoc | 156 |
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}. +*/ + |