/****************************************************************************+ −
**+ −
** Copyright (C) 2010 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$+ −
** No Commercial Usage+ −
** This file contains pre-release code and may not be distributed.+ −
** You may use this file in accordance with the terms and conditions+ −
** contained in the Technology Preview License Agreement accompanying+ −
** this package.+ −
**+ −
** 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.+ −
**+ −
** 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.+ −
*/+ −