source: trunk/doc/src/porting/qt4-scribe.qdoc

/****************************************************************************
**
** Copyright (C) 2011 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:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** 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.
*/