source: trunk/doc/src/qt4-scribe.qdoc@ 321

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

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.

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