1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \group richtext-processing
6 \brief How to use Rich Text Processing APIs.
7 \title Rich Text Processing APIs
12 \title Rich Text Processing
13 \brief An overview of Qt's rich text processing, editing and display features.
15 \ingroup frameworks-technologies
16 \ingroup qt-basic-concepts
17 \ingroup best-practices
19 \nextpage Rich Text Document Structure
21 The Scribe framework provides a set of classes for reading and manipulating
22 structured rich text documents. Unlike previous rich text support in Qt, the
23 new classes are centered around the QTextDocument class rather than raw
24 textual information. This enables the developer to create and modify
25 structured rich text documents without having to prepare content in an
26 intermediate markup format.
28 The information within a document can be accessed via two complementary
29 interfaces: A cursor-based interface is used for editing, and a read-only
30 hierarchical interface provides a high level overview of the document
31 structure. The main advantage of the cursor-based interface is that the
32 text can be edited using operations that mimic a user's interaction with
33 an editor, without losing the underlying structure of the document. The
34 read-only hierarchical interface is most useful when performing operations
35 such as searching and document export.
37 This document is divided up into chapters for convenient reference:
40 \li \l{Rich Text Document Structure} outlines
41 the different kinds of elements in a QTextDocument, and describes how
42 they are arranged in a document structure.
43 \li \l{The QTextCursor Interface} explains how rich
44 text documents can be edited using the cursor-based interface.
45 \li \l{Document Layouts} briefly explains the role of document layouts.
46 \li \l{Common Rich Text Editing Tasks} examines some
47 common tasks that involve reading or manipulating rich text documents.
48 \li \l{Advanced Rich Text Processing} examines advanced rich text editing tasks.
49 \li \l{Supported HTML Subset} lists the HTML tags supported by QTextDocument.
52 \section1 Rich Text Processing APIs
54 Qt provides an extensive collection of classes for parsing, rendering
55 manipulating and editing rich text.
57 \annotatedlist richtext-processing
61 \page richtext-structure.html
62 \previouspage Rich Text Processing
63 \nextpage The QTextCursor Interface
65 \title Rich Text Document Structure
69 Text documents are represented by the QTextDocument class, which
70 contains information about the document's internal representation, its
71 structure, and keeps track of modifications to provide undo/redo
74 The structured representation of a text document presents its contents as
75 a hierarchy of text blocks, frames, tables, and other objects. These provide
76 a logical structure to the document and describe how their contents will be
77 displayed. Generally, frames and tables are used to group other
78 structures while text blocks contain the actual textual information.
80 New elements are created and inserted into the document programmatically
81 \l{richtext-cursor.html}{with a QTextCursor} or by using an editor
82 widget, such as QTextEdit. Elements can be given a particular format when
83 they are created; otherwise they take the cursor's current format for the
88 \li \inlineimage richtext-document.png
89 \li \b{Basic structure}
91 The "top level" of a document might be populated in the way shown.
92 Each document always contains a root frame, and this always contains
93 at least one text block.
95 For documents with some textual content, the root
96 frame usually contains a sequence of blocks and other elements.
98 Sequences of frames and tables are always separated by text blocks in a
99 document, even if the text blocks contain no information. This ensures that
100 new elements can always be inserted between existing structures.
103 In this chapter, we look at each of the structural elements
104 used in a rich text document, outline their features and uses, and show
105 how to examine their contents. Document editing is described in
106 \l{richtext-cursor.html}{The QTextCursor Interface}.
108 \section1 Rich Text Documents
110 QTextDocument objects contain all the information required to construct
112 Text documents can be accessed in two complementary ways: as a linear
113 buffer for editors to use, and as an object hierarchy that is useful to
115 In the hierarchical document model, objects generally correspond to
116 visual elements such as frames, tables, and lists. At a lower level,
117 these elements describe properties such as the text style and alignment.
118 The linear representation of the document is used for editing and
119 manipulation of the document's contents.
121 Although QTextEdit makes it easy to display and edit rich text, documents
122 can also be used independently of any editor widget, for example:
124 \snippet code/doc_src_richtext.cpp 0
126 Alternatively, they can be extracted from an existing editor:
128 \snippet code/doc_src_richtext.cpp 1
130 This flexibility enables applications to handle multiple rich text
131 documents without the overhead of multiple editor widgets, or requiring
132 documents to be stored in some intermediate format.
134 An empty document contains a root frame which itself contains a single
135 empty text block. Frames provide logical separation between parts of the document, but
136 also have properties that determine how they will appear when rendered.
137 A table is a specialized type of frame that consists of a number of
138 cells, arranged into rows and columns, each of which can contain
139 further structure and text. Tables provide management and layout
140 features that allow flexible configurations of cells to be created.
142 Text blocks contain text fragments, each of which specifies text and
143 character format information. Textual properties are defined both at
144 the character level and at the block level. At the character level,
145 properties such as font family, text color, and font weight can be
146 specified. The block level properties control the higher level
147 appearance and behavior of the text, such as the direction of text
148 flow, alignment, and background color.
150 The document structure is not manipulated directly. Editing is
151 performed through a cursor-based interface.
152 The \l{richtext-cursor.html}{text cursor interface}
153 automatically inserts new document elements into the root frame, and
154 ensures that it is padded with empty blocks where necessary.
156 We obtain the root frame in the following manner:
158 \snippet textdocument-frames/mainwindow.cpp rootframe
160 When navigating the document structure, it is useful to begin at the
161 root frame because it provides access to the entire document structure.
164 \section1 Document Elements
166 Rich text documents usually consist of common elements such as paragraphs,
167 frames, tables, and lists. These are represented in a QTextDocument
168 by the QTextBlock, QTextFrame, QTextTable, and QTextList classes.
169 Unlike the other elements in a document, images are represented by
170 specially formatted text fragments. This enables them to be placed
171 formatted inline with the surrounding text.
173 The basic structural building blocks in documents are QTextBlock and
174 QTextFrame. Blocks themselves contain fragments of rich text
175 (QTextFragment), but these do not directly influence the high level
176 structure of a document.
178 Elements which can group together other document elements are typically
179 subclasses of QTextObject, and fall into two categories: Elements that
180 group together text blocks are subclasses of QTextBlockGroup, and those
181 that group together frames and other elements are subclasses of QTextFrame.
183 \section2 Text Blocks
185 Text blocks are provided by the QTextBlock class.
187 Text blocks group together fragments of text with different character formats,
188 and are used to represent paragraphs in the document. Each block
189 typically contains a number of text fragments with different styles.
190 Fragments are created when text is inserted into the document, and more
191 of them are added when the document is edited. The document splits, merges,
192 and removes fragments to efficiently represent the different styles
193 of text in the block.
195 The fragments within a given block can be examined by using a
196 QTextBlock::iterator to traverse the block's internal structure:
198 \snippet textblock-fragments/xmlwriter.cpp 3
199 \snippet textblock-fragments/xmlwriter.cpp 5
200 \snippet textblock-fragments/xmlwriter.cpp 6
202 Blocks are also used to represent list items. As a result, blocks can
203 define their own character formats which contain information about
204 block-level decoration, such as the type of bullet points used for
205 list items. The formatting for the block itself is described by the
206 QTextBlockFormat class, and describes properties such as text alignment,
207 indentation, and background color.
209 Although a given document may contain complex structures, once we have a
210 reference to a valid block in the document, we can navigate between each
211 of the text blocks in the order in which they were written:
213 \snippet textblock-fragments/xmlwriter.cpp 0
214 \snippet textblock-fragments/xmlwriter.cpp 1
215 \snippet textblock-fragments/xmlwriter.cpp 2
217 This method is useful for when you want to extract just the rich text from a
218 document because it ignores frames, tables, and other types of structure.
220 QTextBlock provides comparison operators that make it easier to manipulate
221 blocks: \l{QTextBlock::operator==()}{operator==()} and
222 \l{QTextBlock::operator!=()}{operator!=()} are used to test whether two
223 blocks are the same, and \l{QTextBlock::operator<()}{operator<()} is used
224 to determine which one occurs first in a document.
228 Frames are provided by the QTextFrame class.
230 Text frames group together blocks of text and child frames, creating
231 document structures that are larger than paragraphs. The format of a frame
232 specifies how it is rendered and positioned on the page. Frames are
233 either inserted into the text flow, or they float on the left or right
234 hand side of the page.
235 Each document contains a root frame that contains all the other document
236 elements. As a result, all frames except the root frame have a parent
239 Since text blocks are used to separate other document elements, each
240 frame will always contain at least one text block, and zero or more
241 child frames. We can inspect the contents of a frame by using a
242 QTextFrame::iterator to traverse the frame's child elements:
244 \snippet textdocument-frames/mainwindow.cpp 4
246 Note that the iterator selects both frames and blocks, so it is necessary
247 to check which it is referring to. This allows us to navigate the document
248 structure on a frame-by-frame basis yet still access text blocks if
249 required. Both the QTextBlock::iterator and QTextFrame::iterator classes
250 can be used in complementary ways to extract the required structure from
255 Tables are provided by the QTextTable class.
257 Tables are collections of cells that are arranged in rows and columns.
258 Each table cell is a document element with its own character format, but it
259 can also contain other elements, such as frames and text blocks. Table cells
260 are automatically created when the table is constructed, or when extra rows
261 or columns are added. They can also be moved between tables.
263 QTextTable is a subclass of QTextFrame, so tables are treated like frames
264 in the document structure. For each frame that we encounter in the
265 document, we can test whether it represents a table, and deal with it in a
268 \snippet textdocument-tables/mainwindow.cpp 13
270 The cells within an existing table can be examined by iterating through
271 the rows and columns.
273 \snippet textdocument-tables/mainwindow.cpp 9
274 \snippet textdocument-tables/mainwindow.cpp 10
275 \snippet textdocument-tables/mainwindow.cpp 11
276 \snippet textdocument-tables/mainwindow.cpp 12
281 Lists are provided by the QTextList class.
283 Lists are sequences of text blocks that are formatted in the usual way, but
284 which also provide the standard list decorations such as bullet points and
285 enumerated items. Lists can be nested, and will be indented if the list's
286 format specifies a non-zero indentation.
288 We can refer to each list item by its index in the list:
290 \snippet textdocument-listitems/mainwindow.cpp 0
291 \snippet textdocument-listitems/mainwindow.cpp 1
292 \snippet textdocument-listitems/mainwindow.cpp 2
294 Since QTextList is a subclass of QTextBlockGroup, it does not group the
295 list items as child elements, but instead provides various functions for
296 managing them. This means that any text block we find when traversing a
297 document may actually be a list item. We can ensure that list items are
298 correctly identified by using the following code:
300 \snippet textdocument-listitems/mainwindow.cpp 3
301 \snippet textdocument-listitems/mainwindow.cpp 4
302 \snippet textdocument-listitems/mainwindow.cpp 5
303 \snippet textdocument-listitems/mainwindow.cpp 6
304 \snippet textdocument-listitems/mainwindow.cpp 7
309 Images in QTextDocument are represented by text fragments that reference
310 external images via the resource mechanism. Images are created using the
311 cursor interface, and can be modified later by changing the character
312 format of the image's text fragment:
314 \snippet textdocument-imageformat/main.cpp 0
315 \snippet textdocument-imageformat/main.cpp 1
316 \snippet textdocument-imageformat/main.cpp 2
318 The fragment that represents the image can be found by iterating over
319 the fragments in the text block that contains the image.
323 \page richtext-cursor.html
324 \previouspage Rich Text Document Structure
325 \nextpage Document Layouts
327 \title The QTextCursor Interface
331 Documents can be edited via the interface provided by the QTextCursor
332 class; cursors are either created using a constructor or obtained from
333 an editor widget. The cursor is used to perform editing operations that
334 correspond exactly to those the user is able to make themselves in an
335 editor. As a result, information about the document structure is also
336 available through the cursor, and this allows the structure to be
337 modified. The use of a cursor-oriented interface for editing makes the
338 process of writing a custom editor simpler for developers, since the
339 editing operations can be easily visualized.
341 The QTextCursor class also maintains information about any text it
342 has selected in the document, again following a model that is
343 conceptually similar to the actions made by the user to select text
346 Rich text documents can have multiple cursors
347 associated with them, and each of these contains information about their
348 position in the document and any selections that they may hold. This
349 cursor-based paradigm makes common operations, such as cutting and pasting
350 text, simple to implement programmatically, yet it also allows more complex
351 editing operations to be performed on the document.
353 This chapter describes most of the common editing operations that you
354 will need to perform using a cursor, from basic insertion of text and
355 document elements to more complex manipulation of document structures.
357 \section1 Cursor-Based Editing
359 At the simplest level, text documents are made up of a string of characters,
360 marked up in some way to represent the block structure of the text within the
361 document. QTextCursor provides a cursor-based interface that allows the
362 contents of a QTextDocument to be manipulated at the character level. Since
363 the elements (blocks, frames, tables, etc.) are also encoded in the character
364 stream, the document structure can itself be changed by the cursor.
366 The cursor keeps track of its location within its parent document, and can
367 report information about the surrounding structure, such as the enclosing
368 text block, frame, table, or list. The formats of the enclosing structures
369 can also be directly obtained through the cursor.
371 \section2 Using a Cursor
373 The main use of a cursor is to insert or modify text within a block.
374 We can use a text editor's cursor to do this:
376 \snippet textblock-formats/main.cpp 0
378 Alternatively, we can obtain a cursor directly from a document:
380 \snippet textdocument-images/main.cpp 0
382 The cursor is positioned at the start of the document so that we can write
383 into the first (empty) block in the document.
385 \section2 Grouping Cursor Operations
387 A series of editing operations can be packaged together so that they can
388 be replayed, or undone together in a single action. This is achieved by
389 using the \c beginEditBlock() and \c endEditBlock() functions in the
390 following way, as in the following example where we select the word that
393 \snippet textdocument-selections/mainwindow.cpp 0
395 If editing operations are not grouped, the document automatically records
396 the individual operations so that they can be undone later. Grouping
397 operations into larger packages can make editing more efficient both for
398 the user and for the application, but care has to be taken not to group too
399 many operations together as the user may want find-grained control over the
402 \section2 Multiple Cursors
404 Multiple cursors can be used to simultaneously edit the same document,
405 although only one will be visible to the user in a QTextEdit widget.
406 The QTextDocument ensures that each cursor writes text correctly and
407 does not interfere with any of the others.
410 \snippet textdocument-cursors/main.cpp 0
411 \snippet textdocument-cursors/main.cpp 1
414 \section1 Inserting Document Elements
416 QTextCursor provides several functions that can be used to change the
417 structure of a rich text document. Generally, these functions allow
418 document elements to be created with relevant formatting information,
419 and they are inserted into the document at the cursor's position.
421 The first group of functions insert block-level elements, and update the
422 cursor position, but they do not return the element that was inserted:
425 \li \l{QTextCursor::insertBlock()}{insertBlock()} inserts a new text block
426 (paragraph) into a document at the cursor's position, and moves the
427 cursor to the start of the new block.
428 \li \l{QTextCursor::insertFragment()}{insertFragment()} inserts an existing
429 text fragment into a document at the cursor's position.
430 \li \l{QTextCursor::insertImage()}{insertImage()} inserts an image into a
431 document at the cursor's position.
432 \li \l{QTextCursor::insertText()}{insertText()} inserts text into the
433 document at the cursor's position.
436 You can examine the contents of the element that was inserted through the
439 The second group of functions insert elements that provide structure to
440 the document, and return the structure that was inserted:
443 \li \l{QTextCursor::insertFrame()}{insertFrame()} inserts a frame into the
444 document \e after the cursor's current block, and moves the cursor to
445 the start of the empty block in the new frame.
446 \li \l{QTextCursor::insertList()}{insertList()} inserts a list into the
447 document at the cursor's position, and moves the cursor to the start
448 of the first item in the list.
449 \li \l{QTextCursor::insertTable()}{insertTable()} inserts a table into
450 the document \e after the cursor's current block, and moves the cursor
451 to the start of the block following the table.
454 These elements either contain or group together other elements in the
457 \section2 Text and Text Fragments
459 Text can be inserted into the current block in the current character
460 format, or in a custom format that is specified with the text:
462 \snippet textdocument-charformats/main.cpp 0
464 Once the character format has been used with a cursor, that format becomes
465 the default format for any text inserted with that cursor until another
466 character format is specified.
468 If a cursor is used to insert text without specifying a character format,
469 the text will be given the character format used at that position in the
474 Text blocks are inserted into the document with the
475 \l{QTextCursor::insertBlock()}{insertBlock()} function.
477 \snippet textblock-formats/main.cpp 1
479 The cursor is positioned at the start of the new block.
483 Frames are inserted into a document using the cursor, and will be placed
484 within the cursor's current frame \e after the current block.
485 The following code shows how a frame can be inserted between two text
486 blocks in a document's root frame. We begin by finding the cursor's
489 \snippet textdocument-frames/mainwindow.cpp 0
491 We insert some text in this frame then set up a frame format for the
494 \snippet textdocument-frames/mainwindow.cpp 1
496 The frame format will give the frame an external margin of 32 pixels,
497 internal padding of 8 pixels, and a border that is 4 pixels wide.
498 See the QTextFrameFormat documentation for more information about
501 The frame is inserted into the document after the preceding text:
503 \snippet textdocument-frames/mainwindow.cpp 2
505 We add some text to the document immediately after we insert the frame.
506 Since the text cursor is positioned \e{inside the frame} when it is inserted
507 into the document, this text will also be inserted inside the frame.
509 Finally, we position the cursor outside the frame by taking the last
510 available cursor position inside the frame we recorded earlier:
512 \snippet textdocument-frames/mainwindow.cpp 3
514 The text that we add last is inserted after the child frame in the
515 document. Since each frame is padded with text blocks, this ensures that
516 more elements can always be inserted with a cursor.
520 Tables are inserted into the document using the cursor, and will be
521 placed within the cursor's current frame \e after the current block:
523 \snippet textdocument-tables/mainwindow.cpp 0
524 \snippet textdocument-tables/mainwindow.cpp 3
526 Tables can be created with a specific format that defines the overall
527 properties of the table, such as its alignment, background color, and
528 the cell spacing used. It can also determine the constraints on each
529 column, allowing each of them to have a fixed width, or resize according
530 to the available space.
532 \snippet textdocument-tables/mainwindow.cpp 2
534 The columns in the table created above will each take up a certain
535 percentage of the available width. Note that the table format is
536 optional; if you insert a table without a format, some sensible
537 default values will be used for the table's properties.
539 Since cells can contain other document elements, they too can be
540 formatted and styled as necessary.
542 Text can be added to the table by navigating to each cell with the cursor
545 \snippet textdocument-tables/mainwindow.cpp 4
547 We can create a simple timetable by following this approach:
549 \snippet textdocument-tables/mainwindow.cpp 5
550 \snippet textdocument-tables/mainwindow.cpp 6
551 \snippet textdocument-tables/mainwindow.cpp 7
552 \snippet textdocument-tables/mainwindow.cpp 8
556 Lists of block elements can be automatically created and inserted into the
557 document at the current cursor position. Each list that is created in this
558 way requires a list format to be specified:
560 \snippet textdocument-lists/mainwindow.cpp 0
562 The above code first checks whether the cursor is within an existing list
563 and, if so, gives the list format for the new list a suitable level of
564 indentation. This allows nested lists to be created with increasing
565 levels of indentation. A more sophisticated implementation would also use
566 different kinds of symbol for the bullet points in each level of the list.
570 Inline images are added to documents through the cursor in the usual manner.
571 Unlike many other elements, all of the image properties are specified by the
572 image's format. This means that a QTextImageFormat object has to be
573 created before an image can be inserted:
575 \snippet textdocument-images/main.cpp 1
577 The image name refers to an entry in the application's resource file.
578 The method used to derive this name is described in
579 \l{resources.html}{The Qt Resource System}.
583 Rich text is stored in text documents that can either be created by
584 importing HTML from an external source, or generated using a QTextCursor.
586 \section2 Manipulating Rich Text
588 The easiest way to use a rich text document is through
589 the QTextEdit class, providing an editable view onto a document. The code
590 below imports HTML into a document, and displays the document using a
593 \snippet scribe-overview/main.cpp 1
595 You can retrieve the document from the text edit using the
596 document() function. The document can then be edited programmatically
597 using the QTextCursor class. This class is modeled after a screen
598 cursor, and editing operations follow the same semantics. The following
599 code changes the first line of the document to a bold font, leaving all
600 other font properties untouched. The editor will be automatically
601 updated to reflect the changes made to the underlying document data.
603 \snippet scribe-overview/main.cpp 0
605 Note that the cursor was moved from the start of the first line to the
606 end, but that it retained an anchor at the start of the line. This
607 demonstrates the cursor-based selection facilities of the
610 \section2 Generating a Calendar
612 Rich text can be generated very quickly using the cursor-based
613 approach. The following example shows a simple calendar in a
614 QTextEdit widget with bold headers for the days of the week:
616 \snippet textdocument-blocks/mainwindow.cpp 0
618 \snippet textdocument-blocks/mainwindow.cpp 1
619 \snippet textdocument-blocks/mainwindow.cpp 2
620 \snippet textdocument-blocks/mainwindow.cpp 3
622 The above example demonstrates how simple it is to quickly generate new
623 rich text documents using a minimum amount of code. Although we have
624 generated a crude fixed-pitch calendar to avoid quoting too much code,
625 Scribe provides much more sophisticated layout and formatting features.
629 \page richtext-layouts.html
630 \previouspage The QTextCursor Interface
631 \nextpage Common Rich Text Editing Tasks
633 \title Document Layouts
637 The layout of a document is only relevant when it is to be displayed on
638 a device, or when some information is requested that requires a visual
639 representation of the document. Until this occurs, the document does
640 not need to be formatted and prepared for a device.
644 Each document's layout is managed by a subclass of the
645 QAbstractTextDocumentLayout class. This class provides a common
646 interface for layout and rendering engines. The default rendering
647 behavior is currently implemented in a private class. This approach
648 makes it possible to create custom layouts, and provides the
649 mechanism used when preparing pages for printing or exporting to
650 Portable Document Format (PDF) files.
652 \section1 Example - Shaped Text Layout
654 Sometimes it is important to be able to format plain text within an
655 irregularly-shaped region, perhaps when rendering a custom widget, for
656 example. Scribe provides generic features, such as those provided by
657 the QTextLayout class, to help developers perform word-wrapping and
658 layout tasks without the need to create a document first.
660 \image plaintext-layout.png
662 Formatting and drawing a paragraph of plain text is straightforward.
663 The example below will lay out a paragraph of text, using a single
664 font, around the right hand edge of a circle.
666 \snippet plaintextlayout/window.cpp 0
668 We create a text layout, specifying the text string we want to display
669 and the font to use. We ensure that the text we supplied is formatted
670 correctly by obtaining text lines from the text format, and wrapping
671 the remaining text using the available space. The lines are positioned
672 as we move down the page.
674 The formatted text can be drawn onto a paint device; in the above code,
675 the text is drawn directly onto a widget.
679 \page richtext-common-tasks.html
680 \previouspage Document Layouts
681 \nextpage Advanced Rich Text Processing
683 \title Common Rich Text Editing Tasks
687 There are a number of tasks that are often performed by developers
688 when editing and processing text documents using Qt. These include the use
689 of display widgets such as QTextBrowser and QTextEdit, creation of
690 documents with QTextDocument, editing using a QTextCursor, and
691 exporting the document structure.
692 This document outlines some of the more common ways of using the rich
693 text classes to perform these tasks, showing convenient patterns that can
694 be reused in your own applications.
696 \section1 Using QTextEdit
698 A text editor widget can be constructed and used to display HTML in the
701 \snippet code/doc_src_richtext.cpp 2
703 By default, the text editor contains a document with a root frame, inside
704 which is an empty text block. This document can be obtained so that it can
705 be modified directly by the application:
707 \snippet code/doc_src_richtext.cpp 3
709 The text editor's cursor may also be used to edit a document:
711 \snippet code/doc_src_richtext.cpp 4
713 Although a document can be edited using many cursors at once, a QTextEdit
714 only displays a single cursor at a time. Therefore, if we want to update the
715 editor to display a particular cursor or its selection, we need to set the
716 editor's cursor after we have modified the document:
718 \snippet code/doc_src_richtext.cpp 5
720 \section1 Selecting Text
722 Text is selected by moving the cursor using operations that are similar to
723 those performed by a user in a text editor. To select text between two
724 points in the document, we need to position the cursor at the first point
725 then move it using a special mode (\l{QTextCursor::MoveMode}) with a
726 move operation (\l{QTextCursor::MoveOperation}).
727 When we select the text, we leave the selection anchor at the old cursor
728 position just as the user might do by holding down the Shift key when
731 \snippet textdocument-selections/mainwindow.cpp 1
733 In the above code, a whole word is selected using this method. QTextCursor
734 provides a number of common move operations for selecting individual
735 characters, words, lines, and whole blocks.
737 \section1 Finding Text
739 QTextDocument provides a cursor-based interface for searching, making
740 it easy to find and modify text in the style of a text editor. The following
741 code finds all the instances of a particular word in a document, and changes
744 \snippet textdocument-find/main.cpp 0
745 \snippet textdocument-find/main.cpp 1
747 Note that the cursor does not have to be moved after each search and replace
748 operation; it is always positioned at the end of the word that was just
751 \section1 Printing Documents
753 QTextEdit is designed for the display of large rich text documents that are
754 read on screen, rendering them in the same way as a web browser. As a result,
755 it does not automatically break the contents of the document into page-sized
756 pieces that are suitable for printing.
758 QTextDocument provides a \l{QTextDocument::print()}{print()} function to
759 allow documents to be printed using the QPrinter class. The following code
760 shows how to prepare a document in a QTextEdit for printing with a QPrinter:
762 \snippet textdocument-printing/mainwindow.cpp 0
764 The document is obtained from the text editor, and a QPrinter is constructed
765 then configured using a QPrintDialog. If the user accepts the printer's
766 configuration then the document is formatted and printed using the
767 \l{QTextDocument::print()}{print()} function.
771 \page richtext-advanced-processing.html
772 \previouspage Common Rich Text Editing Tasks
773 \nextpage Supported HTML Subset
775 \title Advanced Rich Text Processing
777 \section1 Handling Large Files
779 Qt does not limit the size of files that are used for text
780 processing. In most cases, this will not present a problem. For
781 especially large files, however, you might experience that your
782 application will become unresponsive or that you will run out of
783 memory. The size of the files you can load depends on your
784 hardware and on Qt's and your own application's implementation.
786 If you are faced with this problem, we recommend that you address the
790 \li You should consider breaking up large paragraphs into smaller
791 ones as Qt handles small paragraphs better. You could also
792 insert line breaks at regular intervals, which will look the
793 same as one large paragraph in a QTextEdit.
794 \li You can reduce the amount of blocks in a QTextDocument with
795 \l{QTextDocument::}{maximumBlockCount()}. The document is only
796 as large as the number of blocks as far as QTextEdit is concerned.
797 \li When adding text to a text edit, it is an advantage to add it
798 in an edit block (see example below). The result is that the
799 text edit does not need to build the entire document structure at once.
802 We give an example of the latter technique from the list. We assume that
803 the text edit is visible.
805 \snippet code/doc_src_richtext.cpp 6
808 Ideas for other sections:
810 * Hiding QTextBlock elements.
811 * Changing the word wrapping mode in QTextEdit. Custom word wrapping?
816 \page richtext-html-subset.html
817 \title Supported HTML Subset
818 \brief Describes the support for HTML markup in text widgets.
820 \previouspage Common Rich Text Editing Tasks
822 Qt's text widgets are able to display rich text, specified using a subset of \l {http://www.w3.org/TR/html401/}{HTML 4}
823 markup. Widgets that use QTextDocument, such as QLabel and QTextEdit, are able to display
824 rich text specified in this way.
828 \section1 Using HTML Markup in Text Widgets
830 Widgets automatically detect HTML markup and display rich text accordingly. For example,
831 setting a label's \l{QLabel::}{text} property with the string \c{"<b>Hello</b> <i>Qt!</i>"}
832 will result in the label displaying text like this: \b{Hello} \e{Qt!}
834 When HTML markup is used for text, Qt follows the rules defined by the \l{http://www.w3.org/TR/html401/}{HTML 4}
835 specification. This includes default properties for text layout, such as the
836 direction of the text flow (left-to-right) which can be changed by applying the
837 \l{#Block Attributes}{\c dir} attribute to blocks of text.
839 \section1 Supported Tags
841 The following table lists the HTML tags supported by Qt's
842 \l{Rich Text Processing}{rich text} engine.
844 \note The functionality implemented for tags listed below is a subset of
845 the full HTML 4 specification. Not all attributes are supported,
846 see comments for each tag.
854 \li Supports the \c href and \c name attributes.
864 \row \li \c blockquote
865 \li Indented paragraph
869 \li Supports the \c bgcolor attribute, which
870 can be a Qt \l{QColor::setNamedColor()}{color name}
871 or a \c #RRGGBB color specification.
876 \li Centered paragraph
891 \li Document division
892 \li Supports the standard \l{block attributes}.
895 \li Supports the standard \l{block attributes}.
898 \li Supports the standard \l{block attributes}.
903 \li Font size, family, and/or color
904 \li Supports the following attributes:
905 \c size, \c face, and \c color (Qt
906 \l{QColor::setNamedColor()}{color names} or
910 \li Supports the standard \l{block attributes}.
913 \li Supports the standard \l{block attributes}.
916 \li Supports the standard \l{block attributes}.
919 \li Supports the standard \l{block attributes}.
922 \li Supports the standard \l{block attributes}.
925 \li Supports the standard \l{block attributes}.
931 \li Supports the \c width attribute, which can
932 be specified as an absolute or relative (\c %) value.
941 \li Supports the \c src, \c source
942 (for Qt 3 compatibility), \c width, and \c height
945 \li User-entered text
949 \li If a text encoding is specified using the \c{meta}
950 tag, it is picked up by Qt::codecForHtml(). Likewise,
951 if an encoding is specified to QTextDocument::toHtml(),
952 the encoding is stored using a \c meta tag, for
954 \c {<meta http-equiv="Content-Type" content="text/html; charset=EUC-JP" />}
959 \li Non-breakable text
963 \li Supports the standard \l{list attributes}.
966 \li Left-aligned by default. Supports the standard
967 \l{block attributes}.
972 \li Qt rich-text document
973 \li Synonym for \c html. Provided for compatibility with
974 earlier versions of Qt.
998 \li Supports the following attributes: \c border,
999 \c bgcolor (Qt \l{QColor::setNamedColor()}{color names}
1000 or \c #RRGGBB), \c cellspacing, \c cellpadding,
1001 \c width (absolute or relative), and \c height.
1007 \li Supports the standard \l{table cell attributes}.
1012 \li Table header cell
1013 \li Supports the standard \l{table cell attributes}.
1016 \li If the \c thead tag is specified, it is used when printing tables
1017 that span multiple pages.
1020 \li The value specified using the \c
1021 title tag is available through
1022 QTextDocument::metaInformation().
1025 \li Supports the \c bgcolor attribute, which
1026 can be a Qt \l{QColor::setNamedColor()}{color name}
1027 or a \c #RRGGBB color specification.
1036 \li Supports the standard \l{list attributes}.
1042 \section1 Block Attributes
1044 The following attributes are supported by the \c div, \c dl, \c
1045 dt, \c h1, \c h2, \c h3, \c h4, \c h5, \c h6, \c p tags:
1048 \li \c align (\c left, \c right, \c center, \c justify)
1049 \li \c dir (\c ltr, \c rtl)
1052 \section1 List Attributes
1054 The following attribute is supported by the \c ol and \c ul tags:
1057 \li \c type (\c 1, \c a, \c A, \c square, \c disc, \c circle)
1060 \section1 Table Cell Attributes
1062 The following attributes are supported by the \c td and \c th
1066 \li \c width (absolute, relative, or no-value)
1067 \li \c bgcolor (Qt \l{QColor::setNamedColor()}{color names} or \c #RRGGBB)
1070 \li \c align (\c left, \c right, \c center, \c justify)
1071 \li \c valign (\c top, \c middle, \c bottom)
1074 \section1 CSS Properties
1075 The following table lists the CSS properties supported by Qt's
1076 \l{Rich Text Processing}{rich text} engine:
1079 \header \li Property
1083 \li \c background-color
1085 \li Background color for elements
1087 \li \c background-image
1089 \li Background image for elements
1092 \li Text foreground color
1093 \row \li \c font-family
1095 \li Font family name
1096 \row \li \c font-size
1097 \li [ small | medium | large | x-large | xx-large ] | <size>pt | <size>px
1098 \li Font size relative to the document font, or specified in points or pixels
1099 \row \li \c font-style
1100 \li [ normal | italic | oblique ]
1102 \row \li \c font-weight
1103 \li [ normal | bold | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 ]
1104 \li Specifies the font weight used for text, where \c normal and \c bold
1105 are mapped to the corresponding QFont weights. Numeric values are
1106 8 times the equivalent QFont weight values.
1107 \row \li \c text-decoration
1108 \li none | [ underline || overline || line-through ]
1109 \li Additional text effects
1111 \li [ [ <'font-style'> || <'font-weight'> ]? <'font-size'> <'font-family'> ]
1112 \li Font shorthand property
1113 \row \li \c text-indent
1115 \li First line text indentation in pixels
1116 \row \li \c white-space
1117 \li normal | pre | nowrap | pre-wrap
1118 \li Declares how whitespace in HTML is handled.
1119 \row \li \c margin-top
1121 \li Top paragraph margin in pixels
1122 \row \li \c margin-bottom
1124 \li Bottom paragraph margin in pixels
1125 \row \li \c margin-left
1127 \li Left paragraph margin in pixels
1128 \row \li \c margin-right
1130 \li Right paragraph margin in pixels
1131 \row \li \c padding-top
1133 \li Top table cell padding in pixels
1134 \row \li \c padding-bottom
1136 \li Bottom table cell padding in pixels
1137 \row \li \c padding-left
1139 \li Left table cell padding in pixels
1140 \row \li \c padding-right
1142 \li Right table cell padding in pixels
1145 \li Shorthand for setting all the padding properties at once.
1146 \row \li \c vertical-align
1147 \li baseline | sub | super | middle | top | bottom
1148 \li Vertical text alignment. For vertical alignment in text table cells only middle, top, and bottom apply.
1149 \row \li \c border-collapse
1150 \li collapse | separate
1151 \li Border Collapse mode for text tables. If set to collapse, cell-spacing will not be applied.
1152 \row \li \c border-color
1154 \li Border color for text tables and table cells.
1155 \row \li \c border-top-color
1157 \li Top border color for table cells.
1158 \row \li \c border-bottom-color
1160 \li Bottom border color for table cells.
1161 \row \li \c border-left-color
1163 \li Left border color for table cells.
1164 \row \li \c border-right-color
1166 \li Right border color for table cells.
1167 \row \li \c border-style
1168 \li none | dotted | dashed | dot-dash | dot-dot-dash | solid | double | groove | ridge | inset | outset
1169 \li Border style for text tables and table cells.
1170 \row \li \c border-top-style
1172 \li Top border style for table cells.
1173 \row \li \c border-bottom-style
1175 \li Bottom border style for table cells.
1176 \row \li \c border-left-style
1178 \li Left border style for table cells.
1179 \row \li \c border-right-style
1181 \li Right border style for table cells.
1182 \row \li \c border-width
1184 \li Width of table or cell border
1185 \row \li \c border-top-width
1187 \li Top border width for table cells.
1188 \row \li \c border-bottom-width
1190 \li Bottom border width for table cells.
1191 \row \li \c border-left-width
1193 \li Left border width for table cells.
1194 \row \li \c border-right-width
1196 \li Right border width for table cells.
1197 \row \li \c border-top
1198 \li <width>px <border-style> <border-color>
1199 \li Shorthand for setting top border width, style and color
1200 \row \li \c border-bottom
1201 \li <width>px <border-style> <border-color>
1202 \li Shorthand for setting bottom border width, style and color
1203 \row \li \c border-left
1204 \li <width>px <border-style> <border-color>
1205 \li Shorthand for setting left border width, style and color
1206 \row \li \c border-right
1207 \li <width>px <border-style> <border-color>
1208 \li Shorthand for setting right border width, style and color
1209 \row \li \c border-top
1210 \li <width>px <border-style> <border-color>
1211 \li Shorthand for setting top border width, style and color
1212 \row \li \c border-bottom
1213 \li <width>px <border-style> <border-color>
1214 \li Shorthand for setting bottom border width, style and color
1216 \li <width>px <border-style> <border-color>
1217 \li Shorthand for setting all four border's width, style and color
1218 \row \li \c background
1219 \li [ <'background-color'> || <'background-image'> ]
1220 \li Background shorthand property
1221 \row \li \c page-break-before
1222 \li [ auto | always ]
1223 \li Make it possible to enforce a page break before the paragraph/table
1224 \row \li \c page-break-after
1225 \li [ auto | always ]
1226 \li Make it possible to enforce a page break after the paragraph/table
1228 \li [ left | right | none ]
1229 \li Specifies where an image or a text will be placed in another element. Note that the \c float property is
1230 only supported for tables and images.
1231 \row \li \c text-transform
1232 \li [ uppercase | lowercase ]
1233 \li Select the transformation that will be performed on the text prior to displaying it.
1234 \row \li \c font-kerning
1235 \li [ normal | none ]
1236 \li Enables or disables kerning between text characters.
1237 \row \li \c font-variant
1239 \li Perform the smallcaps transformation on the text prior to displaying it.
1240 \row \li \c word-spacing
1242 \li Specifies an alternate spacing between each word.
1243 \row \li \c line-height
1244 \li <number>[% | px | pt | cm]
1245 \li Specifies the height of a line. It can be one of the
1248 \li fixed line height in pixels, points, or centimeters.
1249 \li a percentage of the current font size.
1253 \section1 Qt-specific CSS properties
1255 Besides the standard CSS properties listed earlier, the following
1256 Qt-specific properties can also be used to style a text block:
1259 \header \li Property
1263 \li \c -qt-block-indent
1265 \li Indents the text block by the specified no. spaces.
1267 \li \c -qt-list-indent
1269 \li Indents the list items by the specified no. of spaces.
1271 \li \c -qt-list-number-prefix
1273 \li Prefixes the given string to list number in an HTML ordered list.
1275 \li \c -qt-list-number-suffix
1277 \li Suffixes the given string to list number in an HTML ordered list.
1279 \li \c -qt-paragraph-type
1281 \li Hides the text block.
1283 \li \c -qt-table-type
1284 \li \c{root | frame}
1285 \li \c root renders the text blocks inline without borders and
1286 indentation, whereas \c frame renders them on a new line
1287 with a frame around.
1289 \li \c -qt-user-state
1291 \li Adds it as user data for the text block.
1294 \section1 Supported CSS Selectors
1296 All CSS 2.1 selector classes are supported except pseudo-class selectors such
1297 as \c{:first-child}, \c{:visited} and \c{:hover}.
1.9.7