1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** 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. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $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
\li Implement the text object.
\li Register the text object with the layout of the text
document.
\li Set the text object on a QTextCharFormat.
\li Insert a QChar::ObjectReplacementCharacter with that
text char format into the document.
\endlist
The example consists of the following classes:
\list
\li \c{SvgTextObject} implements the text object.
\li \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 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 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 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 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 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 richtext/textobject/window.cpp 1
First, the \c .svg file is opened and its contents are read
into the \c svgData array.
\snippet 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}.
*/
|
