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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
|
/****************************************************************************
**
** Copyright (C) 2009 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: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 qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qt4-scribe.html
\title The Scribe Classes
\contentspage {What's New in Qt 4}{Home}
\previouspage The Arthur Paint System
\nextpage The Qt 4 Main Window Classes
\keyword Scribe
Scribe introduces a set of text layout classes to Qt 4. These classes
replace the old rich text engine found in Qt 3, and provide new features
for processing and laying out both plain and rich text.
\tableofcontents
For more details about how to use the Scribe classes, see the
\l{richtext.html}{Rich Text Processing} document.
\section1 Overview of Scribe
Support for text rendering and layout in Qt 4 has been redesigned
around a system that allows textual content to be represented in a more
flexible way than was possible with Qt 3. Qt 4 also provides a more
convenient programming interface for editing documents. These
improvements are made available through a reimplementation of the
existing text rendering engine, and the introduction of several new
classes.
The following sections provide a brief overview of the main concepts
behind Scribe.
\section2 The Document Interface
Text documents are represented by the QTextDocument class, rather
than by QString objects. Each QTextDocument object contains
information about the document's internal representation, its
structure, and keeps track of modifications to provide undo/redo
facilities.
This approach allows features such as layout management to be
delegated to specialized classes, but also provides a focus for the
framework.
Documents are either converted from external sources or created from
scratch using Qt. The creation process can done by an editor widget,
such as QTextEdit, or by explicit calls to the Scribe API.
Text documents can be accessed in two complementary ways: as a linear
buffer for editors to use, and as an object hierarchy that is useful to
layout engines.
In the hierarchical document model, objects generally correspond to
visual elements such as frames, tables, and lists. At a lower level,
these elements describe properties such as the text style and alignment.
The linear representation of the document is used for editing and
manipulation of the document's contents.
\section2 Document Structure
Each document contains a root frame into which all other structural
elements are placed. This frame contains other structural elements,
including tables, text blocks, and other frames; these can be nested to
an arbitrary depth.
Frames provide logical separation between parts of the document, but
also have properties that determine how they will appear when rendered.
A table is a specialized type of frame that consists of a number of
cells, arranged into rows and columns, each of which can contain
further structure and text. Tables provide management and layout
features that allow flexible configurations of cells to be created.
Text blocks contain text fragments, each of which specifies text and
character format information. Textual properties are defined both at
the character level and at the block level. At the character level,
properties such as font family, text color, and font weight can be
specified. The block level properties control the higher level
appearance and behavior of the text, such as the direction of text
flow, alignment, and background color.
The document structure is not manipulated directly. Editing is
performed through a cursor-based interface.
\section2 Editing and Content Creation
Documents can be edited via the interface provided by the QTextCursor
class; cursors are either created using a constructor or obtained from
an editor widget. The cursor is used to perform editing operations that
correspond exactly to those the user is able to make themselves in an
editor. As a result, information about the document structure is also
available through the cursor, and this allows the structure to be
modified. The use of a cursor-oriented interface for editing makes the
process of writing a custom editor simpler for developers, since the
editing operations can be easily visualized.
The QTextCursor class also maintains information about any text it
has selected in the document, again following a model that is
conceptually similar to the actions made by the user to select text
in an editor.
\section2 Document Layout
The layout of a document is only relevant when it is to be displayed on
a device, or when some information is requested that requires a visual
representation of the document. Until this occurs, the document does
not need to be formatted and prepared for a device.
Each document's layout is managed by a subclass of the
QAbstractTextDocumentLayout class. This class provides a common
interface for layout and rendering engines. The default rendering
behavior is currently implemented in a private class. This approach
makes it possible to create custom layouts, and provides the
mechanism used when preparing pages for printing or exporting to
Portable Document Format (PDF) files.
\section1 Example Code
Here we present two different ways in which the Scribe classes can be
used: for creating and manipulating rich text, and for laying out
plain text.
\section2 Manipulating Rich Text
Rich text is stored in text documents that can either be created by
importing HTML from an external source, or generated using a
QTextCursor. The easiest way to use a rich text document is through
the QTextEdit class, providing an editable view onto a document. The code
below imports HTML into a document, and displays the document using a
text edit widget.
\snippet doc/src/snippets/scribe-overview/main.cpp 1
You can retrieve the document from the text edit using the
document() function. The document can then be edited programmatically
using the QTextCursor class. This class is modeled after a screen
cursor, and editing operations follow the same semantics. The following
code changes the first line of the document to a bold font, leaving all
other font properties untouched. The editor will be automatically
updated to reflect the changes made to the underlying document data.
\snippet doc/src/snippets/scribe-overview/main.cpp 0
Note that the cursor was moved from the start of the first line to the
end, but that it retained an anchor at the start of the line. This
demonstrates the cursor-based selection facilities of the
QTextCursor class.
Rich text can be generated very quickly using the cursor-based
approach. The following example shows a simple calendar in a
QTextEdit widget with bold headers for the days of the week:
\snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 0
\codeline
\snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 1
\snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 2
\snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 3
The above example demonstrates how simple it is to quickly generate new
rich text documents using a minimum amount of code. Although we have
generated a crude fixed-pitch calendar to avoid quoting too much code,
Scribe provides much more sophisticated layout and formatting features.
\section2 Plain Text Layout
Sometimes it is important to be able to format plain text within an
irregularly-shaped region, perhaps when rendering a custom widget, for
example. Scribe provides generic features, such as those provided by
the QTextLayout class, to help developers perform word-wrapping and
layout tasks without the need to create a document first.
\img plaintext-layout.png
Formatting and drawing a paragraph of plain text is straightforward.
The example below will lay out a paragraph of text, using a single
font, around the right hand edge of a circle.
\snippet doc/src/snippets/plaintextlayout/window.cpp 0
We create a text layout, specifying the text string we want to display
and the font to use. We ensure that the text we supplied is formatted
correctly by obtaining text lines from the text format, and wrapping
the remaining text using the available space. The lines are positioned
as we move down the page.
The formatted text can be drawn onto a paint device; in the above code,
the text is drawn directly onto a widget.
\section2 Printing Features
The layout system used to display rich text documents also supports
paged layout of documents, and this is used by Qt to generate output for
printing. The printing process is performed by QPrinter and controlled by
the user via options displayed in a QPrintDialog:
\snippet doc/src/snippets/textdocument-printing/mainwindow.cpp 0
Rich text documents can also be exported as PDF files using QPrinter and
the appropriate print engine:
\snippet demos/textedit/textedit.cpp 0
\section1 Comparison with Qt 3
The cursor-based editing features, combined with the structural document
model, provide a powerful set of tools for manipulating and displaying
rich text documents. These provide features that were unavailable in
Qt 3's public API. The engine used is a complete rewrite and does not
use the rich text engine supplied with Qt 3.
The QTextEdit class in Qt 4 has also been completely rewritten with an
API that is quite different from its Qt 3 counterpart. Some compatibility
methods have been added to allow the widget to be used, for basic cases,
in a way that is familiar to users of Qt 3. This class is provided as a
working example of an editor widget that uses the new API, showing that
it is possible to completely implement a document editor based on the
QTextCursor editing interface.
*/
|
