MCL/sf/mw/qt: comparison doc/src/porting/qt4-scribe.qdoc

equal deleted inserted replaced

--1:000000000000
+:1918ee327afb
+/****************************************************************************
+**
+** 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$
+** 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.
+*/