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 | */
|
---|