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

Last change on this file since 349 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 6.7 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information (qt-info@nokia.com)
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at qt-sales@nokia.com.
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \example richtext/textobject
44 \title Text Object Example
45
46 The Text Object example shows how to insert an SVG file into a
47 QTextDocument.
48
49 \image textobject-example.png
50
51 A QTextDocument consists of a hierarchy of elements, such as text blocks and
52 frames. A text object describes the structure or format of one or more of these
53 elements. For instance, images imported from HTML are implemented using text
54 objects. Text objects are used by the document's
55 \l{QAbstractTextDocumentLayout}{layout} to lay out and render (paint) the
56 document. Each object knows how to paint the elements they govern, and
57 calculates their size.
58
59 To be able to insert an SVG image into a text document, we create
60 a text object, and implement painting for that object. This object
61 can then be \l{QTextCharFormat::setObjectType()}{set} on a
62 QTextCharFormat. We also register the text object with the layout
63 of the document, enabling it to draw \l{QTextCharFormat}s governed
64 by our text object. We can summarize the procedure with the
65 following steps:
66
67 \list
68 \o Implement the text object.
69 \o Register the text object with the layout of the text
70 document.
71 \o Set the text object on a QTextCharFormat.
72 \o Insert a QChar::ObjectReplacementCharacter with that
73 text char format into the document.
74 \endlist
75
76 The example consists of the following classes:
77
78 \list
79 \o \c{SvgTextObject} implements the text object.
80 \o \c{Window} shows a QTextEdit into which SVG images can be
81 inserted.
82 \endlist
83
84 \section1 SvgTextObject Class Definition
85
86 Let's take a look at the header file of \c {SvgTextObject}:
87
88 \snippet examples/richtext/textobject/svgtextobject.h 0
89
90 A text object is a QObject that implements QTextObjectInterface.
91 Note that the first class inherited must be QObject, and that
92 you must use Q_INTERFACES to let Qt know that your class
93 implements QTextObjectInterface.
94
95 The document layout keeps a collection of text objects stored as
96 \l{QObject}s, each of which has an associated object type. The
97 layout casts the QObject for the associated object type into the
98 QTextObjectInterface.
99
100 The \l{QTextObjectInterface::}{intrinsicSize()} and
101 \l{QTextObjectInterface::}{drawObject()} functions are then used
102 to calculate the size of the text object and draw it.
103
104 \section1 SvgTextObject Class Implementation
105
106 We start of by taking a look at the
107 \l{QTextObjectInterface::}{intrinsicSize()} function:
108
109 \snippet examples/richtext/textobject/svgtextobject.cpp 0
110
111 \c intrinsicSize() is called by the layout to calculate the size
112 of the text object. Notice that we have drawn the SVG image on a
113 QImage. This is because SVG rendering is quite expensive. The
114 example would lag seriously for large images if we drew them
115 with a QSvgRenderer each time.
116
117 \snippet examples/richtext/textobject/svgtextobject.cpp 1
118
119 In \c drawObject(), we paint the SVG image using the QPainter
120 provided by the layout.
121
122 \section1 Window Class Definition
123
124 The \c Window class is a self-contained window that has a
125 QTextEdit in which SVG images can be inserted.
126
127 \snippet examples/richtext/textobject/window.h 0
128
129 The \c insertTextObject() slot inserts an SVG image at the current
130 cursor position, while \c setupTextObject() creates and registers
131 the SvgTextObject with the layout of the text edit's document.
132
133 The constructor simply calls \c setupTextObject() and \c
134 setupGui(), which creates and lays out the widgets of the \c
135 Window.
136
137 \section1 Window Class Implementation
138
139 We will now take a closer look at the functions that are relevant
140 to our text object, starting with the \c setupTextObject()
141 function.
142
143 \snippet examples/richtext/textobject/window.cpp 3
144
145 \c {SvgTextFormat}'s value is the number of our object type. It is
146 used to identify object types by the document layout.
147
148 Note that we only create one SvgTextObject instance; it will be
149 used for all QTextCharFormat's with the \c SvgTextFormat object
150 type.
151
152 Let's move on to the \c insertTextObject() function:
153
154 \snippet examples/richtext/textobject/window.cpp 1
155
156 First, the \c .svg file is opened and its contents are read
157 into the \c svgData array.
158
159 \snippet examples/richtext/textobject/window.cpp 2
160
161 To speed things up, we buffer the SVG image in a QImage. We use
162 \l{QTextFormat::}{setProperty()} to store the QImage in the in the
163 QTextCharFormat. We can retrieve it later with
164 \l{QTextCharFormat::}{property()}.
165
166 We insert the char format in the standard way - using a
167 QTextCursor. Notice that we use the special QChar
168 \l{QChar::}{ObjectReplacementCharacter}.
169*/
170
Note: See TracBrowser for help on using the repository browser.