diff options
Diffstat (limited to 'doc/src/qt4-scribe.qdoc')
| -rw-r--r-- | doc/src/qt4-scribe.qdoc | 257 |
1 files changed, 0 insertions, 257 deletions
diff --git a/doc/src/qt4-scribe.qdoc b/doc/src/qt4-scribe.qdoc deleted file mode 100644 index 64037cf..0000000 --- a/doc/src/qt4-scribe.qdoc +++ /dev/null @@ -1,257 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** 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 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 http://qt.nokia.com/contact. -** $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. -*/ |