Long live Qt 4.5!

1 files changed, 257 insertions, 0 deletions

diff --git a/doc/src/qt4-scribe.qdoc b/doc/src/qt4-scribe.qdoc
new file mode 100644
index 0000000..5061a82
--- /dev/null
+++ b/doc/src/qt4-scribe.qdoc
@@ -0,0 +1,257 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, 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 are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@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.
+*/