Viadeo Twitter Google Bookmarks ! Facebook Digg MySpace Yahoo MyWeb Blinklist Netvouz Reddit Simpy StumbleUpon Bookmarks Windows Live Favorites 
Logo Documentation Qt ·  Page d'accueil  ·  Toutes les classes  ·  Toutes les fonctions  ·  Vues d'ensemble  · 

The Scribe Classes

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.

For more details about how to use the Scribe classes, see the Rich Text Processing document.

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.

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.

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.

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.

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.

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.

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.

     QTextEdit *editor = new QTextEdit(parent);

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.

     QTextDocument *document = edit->document();
     QTextCursor cursor(document);

     cursor.movePosition(QTextCursor::EndOfLine, QTextCursor::KeepAnchor);

     QTextCharFormat format;


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:

     editor = new QTextEdit(this);

     QTextCursor cursor(editor->textCursor());

     QTextCharFormat format(cursor.charFormat());

     QTextCharFormat boldFormat = format;

     cursor.insertText(" ", boldFormat);

     QDate date = QDate::currentDate();
     int year = date.year(), month = date.month();

     for (int weekDay = 1; weekDay <= 7; ++weekDay) {
         cursor.insertText(QString("%1 ").arg(QDate::shortDayName(weekDay), 3),

     cursor.insertText(" ", format);

     for (int column = 1; column < QDate(year, month, 1).dayOfWeek(); ++column) {
         cursor.insertText("    ", format);

     for (int day = 1; day <= date.daysInMonth(); ++day) {
         int weekDay = QDate(year, month, day).dayOfWeek();

         if (QDate(year, month, day) == date)
             cursor.insertText(QString("%1 ").arg(day, 3), boldFormat);
             cursor.insertText(QString("%1 ").arg(day, 3), format);

         if (weekDay == 7) {
             cursor.insertText(" ", format);

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.

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.

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.

     QTextLayout textLayout(text, font);
     qreal margin = 10;
     qreal radius = qMin(width()/2.0, height()/2.0) - margin;
     QFontMetrics fm(font);

     qreal lineHeight = fm.height();
     qreal y = 0;


     while (1) {
         // create a new line
         QTextLine line = textLayout.createLine();
         if (!line.isValid())

         qreal x1 = qMax(0.0, pow(pow(radius,2)-pow(radius-y,2), 0.5));
         qreal x2 = qMax(0.0, pow(pow(radius,2)-pow(radius-(y+lineHeight),2), 0.5));
         qreal x = qMax(x1, x2) + margin;
         qreal lineWidth = (width() - margin) - x;

         line.setPosition(QPointF(x, margin+y));
         y += line.height();


     QPainter painter;
     painter.fillRect(rect(), Qt::white);
     textLayout.draw(&painter, QPoint(0,0));

     painter.drawEllipse(QRectF(-radius, margin, 2*radius, 2*radius));

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.

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:

     QTextDocument *document = editor->document();
     QPrinter printer;

     QPrintDialog *dlg = new QPrintDialog(&printer, this);
     if (dlg->exec() != QDialog::Accepted)


Rich text documents can also be exported as PDF files using QPrinter and the appropriate print engine:

     QString fileName = QFileDialog::getSaveFileName(this, "Export PDF",
                                                     QString(), "*.pdf");
     if (!fileName.isEmpty()) {
         if (QFileInfo(fileName).suffix().isEmpty())
         QPrinter printer(QPrinter::HighResolution);

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.


Best Of

Actualités les plus lues

  1. « Quelque chose ne va vraiment pas avec les développeurs "modernes" », un développeur à "l'ancienne" critique la multiplication des bibliothèques 44
  2. Microsoft ouvre aux autres compilateurs C++ AMP, la spécification pour la conception d'applications parallèles C++ utilisant le GPU 22
  3. Les développeurs ignorent-ils trop les failles découvertes dans leur code ? Prenez-vous en compte les remarques des autres ? 17
  4. RIM : « 13 % des développeurs ont gagné plus de 100 000 $ sur l'AppWord », Qt et open-source au menu du BlackBerry DevCon Europe 0
  5. BlackBerry 10 : premières images du prochain OS de RIM qui devrait intégrer des widgets et des tuiles inspirées de Windows Phone 0
  6. Quelles nouveautés de C++11 Visual C++ doit-il rapidement intégrer ? Donnez-nous votre avis 10
  7. Adieu qmake, bienvenue qbs : Qt Building Suite, un outil déclaratif et extensible pour la compilation de projets Qt 17
Page suivante

Le Qt Quarterly au hasard


Les développeurs viennent de Mars, les designers de Vénus

Qt Quarterly est la revue trimestrielle proposée par Nokia et à destination des développeurs Qt. Ces articles d'une grande qualité technique sont rédigés par des experts Qt. Lire l'article.



Liens utiles


  • Vous souhaitez rejoindre la rédaction ou proposer un tutoriel, une traduction, une question... ? Postez dans le forum Contribuez ou contactez-nous par MP ou par email (voir en bas de page).

Qt dans le magazine

Cette page est une traduction d'une page de la documentation de Qt, écrite par Nokia Corporation and/or its subsidiary(-ies). Les éventuels problèmes résultant d'une mauvaise traduction ne sont pas imputables à Nokia. Qt 4.7
Copyright © 2012 Developpez LLC. Tous droits réservés Developpez LLC. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents et images sans l'autorisation expresse de Developpez LLC. Sinon, vous encourez selon la loi jusqu'à 3 ans de prison et jusqu'à 300 000 E de dommages et intérêts. Cette page est déposée à la SACD.
Vous avez déniché une erreur ? Un bug ? Une redirection cassée ? Ou tout autre problème, quel qu'il soit ? Ou bien vous désirez participer à ce projet de traduction ? N'hésitez pas à nous contacter ou par MP !

Hébergement Web