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.
14 \ingroup explanations-ui
15 \ingroup frameworks-technologies
16 \ingroup qt-basic-concepts
18 \nextpage Rich Text Document Structure
20 The Scribe framework provides a set of classes for reading and manipulating
21 structured rich text documents. Unlike previous rich text support in Qt, the
22 new classes are centered around the QTextDocument class rather than raw
23 textual information. This enables the developer to create and modify
24 structured rich text documents without having to prepare content in an
25 intermediate markup format.
27 The information within a document can be accessed via two complementary
28 interfaces: A cursor-based interface is used for editing, and a read-only
29 hierarchical interface provides a high level overview of the document
30 structure. The main advantage of the cursor-based interface is that the
31 text can be edited using operations that mimic a user's interaction with
32 an editor, without losing the underlying structure of the document. The
33 read-only hierarchical interface is most useful when performing operations
34 such as searching and document export.
36 This document is divided up into chapters for convenient reference:
39 \li \l{Rich Text Document Structure} outlines
40 the different kinds of elements in a QTextDocument, and describes how
41 they are arranged in a document structure.
42 \li \l{The QTextCursor Interface} explains how rich
43 text documents can be edited using the cursor-based interface.
44 \li \l{Document Layouts} briefly explains the role of document layouts.
45 \li \l{Common Rich Text Editing Tasks} examines some
46 common tasks that involve reading or manipulating rich text documents.
47 \li \l{Advanced Rich Text Processing} examines advanced rich text editing tasks.
48 \li \l{Supported HTML Subset} lists the HTML tags supported by QTextDocument.
51 \section1 Rich Text Processing APIs
53 Qt provides an extensive collection of classes for parsing, rendering
54 manipulating and editing rich text.
56 \annotatedlist richtext-processing
60 \page richtext-structure.html
61 \previouspage Rich Text Processing
62 \nextpage The QTextCursor Interface
64 \title Rich Text Document Structure
68 Text documents are represented by the QTextDocument class, which
69 contains information about the document's internal representation, its
70 structure, and keeps track of modifications to provide undo/redo
73 The structured representation of a text document presents its contents as
74 a hierarchy of text blocks, frames, tables, and other objects. These provide
75 a logical structure to the document and describe how their contents will be
76 displayed. Generally, frames and tables are used to group other
77 structures while text blocks contain the actual textual information.
79 New elements are created and inserted into the document programmatically
80 \l{richtext-cursor.html}{with a QTextCursor} or by using an editor
81 widget, such as QTextEdit. Elements can be given a particular format when
82 they are created; otherwise they take the cursor's current format for the
87 \li \inlineimage richtext-document.png
88 \li \b{Basic structure}
90 The "top level" of a document might be populated in the way shown.
91 Each document always contains a root frame, and this always contains
92 at least one text block.
94 For documents with some textual content, the root
95 frame usually contains a sequence of blocks and other elements.
97 Sequences of frames and tables are always separated by text blocks in a
98 document, even if the text blocks contain no information. This ensures that
99 new elements can always be inserted between existing structures.
102 In this chapter, we look at each of the structural elements
103 used in a rich text document, outline their features and uses, and show
104 how to examine their contents. Document editing is described in
105 \l{richtext-cursor.html}{The QTextCursor Interface}.
107 \section1 Rich Text Documents
109 QTextDocument objects contain all the information required to construct
111 Text documents can be accessed in two complementary ways: as a linear
112 buffer for editors to use, and as an object hierarchy that is useful to
114 In the hierarchical document model, objects generally correspond to
115 visual elements such as frames, tables, and lists. At a lower level,
116 these elements describe properties such as the text style and alignment.
117 The linear representation of the document is used for editing and
118 manipulation of the document's contents.
120 Although QTextEdit makes it easy to display and edit rich text, documents
121 can also be used independently of any editor widget, for example:
123 \snippet code/doc_src_richtext.cpp 0
125 Alternatively, they can be extracted from an existing editor:
127 \snippet code/doc_src_richtext.cpp 1
129 This flexibility enables applications to handle multiple rich text
130 documents without the overhead of multiple editor widgets, or requiring
131 documents to be stored in some intermediate format.
133 An empty document contains a root frame which itself contains a single
134 empty text block. Frames provide logical separation between parts of the document, but
135 also have properties that determine how they will appear when rendered.
136 A table is a specialized type of frame that consists of a number of
137 cells, arranged into rows and columns, each of which can contain
138 further structure and text. Tables provide management and layout
139 features that allow flexible configurations of cells to be created.
141 Text blocks contain text fragments, each of which specifies text and
142 character format information. Textual properties are defined both at
143 the character level and at the block level. At the character level,
144 properties such as font family, text color, and font weight can be
145 specified. The block level properties control the higher level
146 appearance and behavior of the text, such as the direction of text
147 flow, alignment, and background color.
149 The document structure is not manipulated directly. Editing is
150 performed through a cursor-based interface.
151 The \l{richtext-cursor.html}{text cursor interface}
152 automatically inserts new document elements into the root frame, and
153 ensures that it is padded with empty blocks where necessary.
155 We obtain the root frame in the following manner:
157 \snippet textdocument-frames/mainwindow.cpp rootframe
159 When navigating the document structure, it is useful to begin at the
160 root frame because it provides access to the entire document structure.
163 \section1 Document Elements
165 Rich text documents usually consist of common elements such as paragraphs,
166 frames, tables, and lists. These are represented in a QTextDocument
167 by the QTextBlock, QTextFrame, QTextTable, and QTextList classes.
168 Unlike the other elements in a document, images are represented by
169 specially formatted text fragments. This enables them to be placed
170 formatted inline with the surrounding text.
172 The basic structural building blocks in documents are QTextBlock and
173 QTextFrame. Blocks themselves contain fragments of rich text
174 (QTextFragment), but these do not directly influence the high level
175 structure of a document.
177 Elements which can group together other document elements are typically
178 subclasses of QTextObject, and fall into two categories: Elements that
179 group together text blocks are subclasses of QTextBlockGroup, and those
180 that group together frames and other elements are subclasses of QTextFrame.
182 \section2 Text Blocks
184 Text blocks are provided by the QTextBlock class.
186 Text blocks group together fragments of text with different character formats,
187 and are used to represent paragraphs in the document. Each block
188 typically contains a number of text fragments with different styles.
189 Fragments are created when text is inserted into the document, and more
190 of them are added when the document is edited. The document splits, merges,
191 and removes fragments to efficiently represent the different styles
192 of text in the block.
194 The fragments within a given block can be examined by using a
195 QTextBlock::iterator to traverse the block's internal structure:
197 \snippet textblock-fragments/xmlwriter.cpp 3
198 \snippet textblock-fragments/xmlwriter.cpp 5
199 \snippet textblock-fragments/xmlwriter.cpp 6
201 Blocks are also used to represent list items. As a result, blocks can
202 define their own character formats which contain information about
203 block-level decoration, such as the type of bullet points used for
204 list items. The formatting for the block itself is described by the
205 QTextBlockFormat class, and describes properties such as text alignment,
206 indentation, and background color.
208 Although a given document may contain complex structures, once we have a
209 reference to a valid block in the document, we can navigate between each
210 of the text blocks in the order in which they were written:
212 \snippet textblock-fragments/xmlwriter.cpp 0
213 \snippet textblock-fragments/xmlwriter.cpp 1
214 \snippet textblock-fragments/xmlwriter.cpp 2
216 This method is useful for when you want to extract just the rich text from a
217 document because it ignores frames, tables, and other types of structure.
219 QTextBlock provides comparison operators that make it easier to manipulate
220 blocks: \l{QTextBlock::operator==()}{operator==()} and
221 \l{QTextBlock::operator!=()}{operator!=()} are used to test whether two
222 blocks are the same, and \l{QTextBlock::operator<()}{operator<()} is used
223 to determine which one occurs first in a document.
227 Frames are provided by the QTextFrame class.
229 Text frames group together blocks of text and child frames, creating
230 document structures that are larger than paragraphs. The format of a frame
231 specifies how it is rendered and positioned on the page. Frames are
232 either inserted into the text flow, or they float on the left or right
233 hand side of the page.
234 Each document contains a root frame that contains all the other document
235 elements. As a result, all frames except the root frame have a parent
238 Since text blocks are used to separate other document elements, each
239 frame will always contain at least one text block, and zero or more
240 child frames. We can inspect the contents of a frame by using a
241 QTextFrame::iterator to traverse the frame's child elements:
243 \snippet textdocument-frames/mainwindow.cpp 4
245 Note that the iterator selects both frames and blocks, so it is necessary
246 to check which it is referring to. This allows us to navigate the document
247 structure on a frame-by-frame basis yet still access text blocks if
248 required. Both the QTextBlock::iterator and QTextFrame::iterator classes
249 can be used in complementary ways to extract the required structure from
254 Tables are provided by the QTextTable class.
256 Tables are collections of cells that are arranged in rows and columns.
257 Each table cell is a document element with its own character format, but it
258 can also contain other elements, such as frames and text blocks. Table cells
259 are automatically created when the table is constructed, or when extra rows
260 or columns are added. They can also be moved between tables.
262 QTextTable is a subclass of QTextFrame, so tables are treated like frames
263 in the document structure. For each frame that we encounter in the
264 document, we can test whether it represents a table, and deal with it in a
267 \snippet textdocument-tables/mainwindow.cpp 13
269 The cells within an existing table can be examined by iterating through
270 the rows and columns.
272 \snippet textdocument-tables/mainwindow.cpp 9
273 \snippet textdocument-tables/mainwindow.cpp 10
274 \snippet textdocument-tables/mainwindow.cpp 11
275 \snippet textdocument-tables/mainwindow.cpp 12
280 Lists are provided by the QTextList class.
282 Lists are sequences of text blocks that are formatted in the usual way, but
283 which also provide the standard list decorations such as bullet points and
284 enumerated items. Lists can be nested, and will be indented if the list's
285 format specifies a non-zero indentation.
287 We can refer to each list item by its index in the list:
289 \snippet textdocument-listitems/mainwindow.cpp 0
290 \snippet textdocument-listitems/mainwindow.cpp 1
291 \snippet textdocument-listitems/mainwindow.cpp 2
293 Since QTextList is a subclass of QTextBlockGroup, it does not group the
294 list items as child elements, but instead provides various functions for
295 managing them. This means that any text block we find when traversing a
296 document may actually be a list item. We can ensure that list items are
297 correctly identified by using the following code:
299 \snippet textdocument-listitems/mainwindow.cpp 3
300 \snippet textdocument-listitems/mainwindow.cpp 4
301 \snippet textdocument-listitems/mainwindow.cpp 5
302 \snippet textdocument-listitems/mainwindow.cpp 6
303 \snippet textdocument-listitems/mainwindow.cpp 7
308 Images in QTextDocument are represented by text fragments that reference
309 external images via the resource mechanism. Images are created using the
310 cursor interface, and can be modified later by changing the character
311 format of the image's text fragment:
313 \snippet textdocument-imageformat/main.cpp 0
314 \snippet textdocument-imageformat/main.cpp 1
315 \snippet textdocument-imageformat/main.cpp 2
317 The fragment that represents the image can be found by iterating over
318 the fragments in the text block that contains the image.
322 \page richtext-cursor.html
323 \previouspage Rich Text Document Structure
324 \nextpage Document Layouts
326 \title The QTextCursor Interface
330 Documents can be edited via the interface provided by the QTextCursor
331 class; cursors are either created using a constructor or obtained from
332 an editor widget. The cursor is used to perform editing operations that
333 correspond exactly to those the user is able to make themselves in an
334 editor. As a result, information about the document structure is also
335 available through the cursor, and this allows the structure to be
336 modified. The use of a cursor-oriented interface for editing makes the
337 process of writing a custom editor simpler for developers, since the
338 editing operations can be easily visualized.
340 The QTextCursor class also maintains information about any text it
341 has selected in the document, again following a model that is
342 conceptually similar to the actions made by the user to select text
345 Rich text documents can have multiple cursors
346 associated with them, and each of these contains information about their
347 position in the document and any selections that they may hold. This
348 cursor-based paradigm makes common operations, such as cutting and pasting
349 text, simple to implement programmatically, yet it also allows more complex
350 editing operations to be performed on the document.
352 This chapter describes most of the common editing operations that you
353 will need to perform using a cursor, from basic insertion of text and
354 document elements to more complex manipulation of document structures.
356 \section1 Cursor-Based Editing
358 At the simplest level, text documents are made up of a string of characters,
359 marked up in some way to represent the block structure of the text within the
360 document. QTextCursor provides a cursor-based interface that allows the
361 contents of a QTextDocument to be manipulated at the character level. Since
362 the elements (blocks, frames, tables, etc.) are also encoded in the character
363 stream, the document structure can itself be changed by the cursor.
365 The cursor keeps track of its location within its parent document, and can
366 report information about the surrounding structure, such as the enclosing
367 text block, frame, table, or list. The formats of the enclosing structures
368 can also be directly obtained through the cursor.
370 \section2 Using a Cursor
372 The main use of a cursor is to insert or modify text within a block.
373 We can use a text editor's cursor to do this:
375 \snippet textblock-formats/main.cpp 0
377 Alternatively, we can obtain a cursor directly from a document:
379 \snippet textdocument-images/main.cpp 0
381 The cursor is positioned at the start of the document so that we can write
382 into the first (empty) block in the document.
384 \section2 Grouping Cursor Operations
386 A series of editing operations can be packaged together so that they can
387 be replayed, or undone together in a single action. This is achieved by
388 using the \c beginEditBlock() and \c endEditBlock() functions in the
389 following way, as in the following example where we select the word that
392 \snippet textdocument-selections/mainwindow.cpp 0
394 If editing operations are not grouped, the document automatically records
395 the individual operations so that they can be undone later. Grouping
396 operations into larger packages can make editing more efficient both for
397 the user and for the application, but care has to be taken not to group too
398 many operations together as the user may want find-grained control over the
401 \section2 Multiple Cursors
403 Multiple cursors can be used to simultaneously edit the same document,
404 although only one will be visible to the user in a QTextEdit widget.
405 The QTextDocument ensures that each cursor writes text correctly and
406 does not interfere with any of the others.
409 \snippet textdocument-cursors/main.cpp 0
410 \snippet textdocument-cursors/main.cpp 1
413 \section1 Inserting Document Elements
415 QTextCursor provides several functions that can be used to change the
416 structure of a rich text document. Generally, these functions allow
417 document elements to be created with relevant formatting information,
418 and they are inserted into the document at the cursor's position.
420 The first group of functions insert block-level elements, and update the
421 cursor position, but they do not return the element that was inserted:
424 \li \l{QTextCursor::insertBlock()}{insertBlock()} inserts a new text block
425 (paragraph) into a document at the cursor's position, and moves the
426 cursor to the start of the new block.
427 \li \l{QTextCursor::insertFragment()}{insertFragment()} inserts an existing
428 text fragment into a document at the cursor's position.
429 \li \l{QTextCursor::insertImage()}{insertImage()} inserts an image into a
430 document at the cursor's position.
431 \li \l{QTextCursor::insertText()}{insertText()} inserts text into the
432 document at the cursor's position.
435 You can examine the contents of the element that was inserted through the
438 The second group of functions insert elements that provide structure to
439 the document, and return the structure that was inserted:
442 \li \l{QTextCursor::insertFrame()}{insertFrame()} inserts a frame into the
443 document \e after the cursor's current block, and moves the cursor to
444 the start of the empty block in the new frame.
445 \li \l{QTextCursor::insertList()}{insertList()} inserts a list into the
446 document at the cursor's position, and moves the cursor to the start
447 of the first item in the list.
448 \li \l{QTextCursor::insertTable()}{insertTable()} inserts a table into
449 the document \e after the cursor's current block, and moves the cursor
450 to the start of the block following the table.
453 These elements either contain or group together other elements in the
456 \section2 Text and Text Fragments
458 Text can be inserted into the current block in the current character
459 format, or in a custom format that is specified with the text:
461 \snippet textdocument-charformats/main.cpp 0
463 Once the character format has been used with a cursor, that format becomes
464 the default format for any text inserted with that cursor until another
465 character format is specified.
467 If a cursor is used to insert text without specifying a character format,
468 the text will be given the character format used at that position in the
473 Text blocks are inserted into the document with the
474 \l{QTextCursor::insertBlock()}{insertBlock()} function.
476 \snippet textblock-formats/main.cpp 1
478 The cursor is positioned at the start of the new block.
482 Frames are inserted into a document using the cursor, and will be placed
483 within the cursor's current frame \e after the current block.
484 The following code shows how a frame can be inserted between two text
485 blocks in a document's root frame. We begin by finding the cursor's
488 \snippet textdocument-frames/mainwindow.cpp 0
490 We insert some text in this frame then set up a frame format for the
493 \snippet textdocument-frames/mainwindow.cpp 1
495 The frame format will give the frame an external margin of 32 pixels,
496 internal padding of 8 pixels, and a border that is 4 pixels wide.
497 See the QTextFrameFormat documentation for more information about
500 The frame is inserted into the document after the preceding text:
502 \snippet textdocument-frames/mainwindow.cpp 2
504 We add some text to the document immediately after we insert the frame.
505 Since the text cursor is positioned \e{inside the frame} when it is inserted
506 into the document, this text will also be inserted inside the frame.
508 Finally, we position the cursor outside the frame by taking the last
509 available cursor position inside the frame we recorded earlier:
511 \snippet textdocument-frames/mainwindow.cpp 3
513 The text that we add last is inserted after the child frame in the
514 document. Since each frame is padded with text blocks, this ensures that
515 more elements can always be inserted with a cursor.
519 Tables are inserted into the document using the cursor, and will be
520 placed within the cursor's current frame \e after the current block:
522 \snippet textdocument-tables/mainwindow.cpp 0
523 \snippet textdocument-tables/mainwindow.cpp 3
525 Tables can be created with a specific format that defines the overall
526 properties of the table, such as its alignment, background color, and
527 the cell spacing used. It can also determine the constraints on each
528 column, allowing each of them to have a fixed width, or resize according
529 to the available space.
531 \snippet textdocument-tables/mainwindow.cpp 2
533 The columns in the table created above will each take up a certain
534 percentage of the available width. Note that the table format is
535 optional; if you insert a table without a format, some sensible
536 default values will be used for the table's properties.
538 Since cells can contain other document elements, they too can be
539 formatted and styled as necessary.
541 Text can be added to the table by navigating to each cell with the cursor
544 \snippet textdocument-tables/mainwindow.cpp 4
546 We can create a simple timetable by following this approach:
548 \snippet textdocument-tables/mainwindow.cpp 5
549 \snippet textdocument-tables/mainwindow.cpp 6
550 \snippet textdocument-tables/mainwindow.cpp 7
551 \snippet textdocument-tables/mainwindow.cpp 8
555 Lists of block elements can be automatically created and inserted into the
556 document at the current cursor position. Each list that is created in this
557 way requires a list format to be specified:
559 \snippet textdocument-lists/mainwindow.cpp 0
561 The above code first checks whether the cursor is within an existing list
562 and, if so, gives the list format for the new list a suitable level of
563 indentation. This allows nested lists to be created with increasing
564 levels of indentation. A more sophisticated implementation would also use
565 different kinds of symbol for the bullet points in each level of the list.
569 Inline images are added to documents through the cursor in the usual manner.
570 Unlike many other elements, all of the image properties are specified by the
571 image's format. This means that a QTextImageFormat object has to be
572 created before an image can be inserted:
574 \snippet textdocument-images/main.cpp 1
576 The image name refers to an entry in the application's resource file.
577 The method used to derive this name is described in
578 \l{resources.html}{The Qt Resource System}.
582 Rich text is stored in text documents that can either be created by
583 importing HTML from an external source, or generated using a QTextCursor.
585 \section2 Manipulating Rich Text
587 The easiest way to use a rich text document is through
588 the QTextEdit class, providing an editable view onto a document. The code
589 below imports HTML into a document, and displays the document using a
592 \snippet scribe-overview/main.cpp 1
594 You can retrieve the document from the text edit using the
595 document() function. The document can then be edited programmatically
596 using the QTextCursor class. This class is modeled after a screen
597 cursor, and editing operations follow the same semantics. The following
598 code changes the first line of the document to a bold font, leaving all
599 other font properties untouched. The editor will be automatically
600 updated to reflect the changes made to the underlying document data.
602 \snippet scribe-overview/main.cpp 0
604 Note that the cursor was moved from the start of the first line to the
605 end, but that it retained an anchor at the start of the line. This
606 demonstrates the cursor-based selection facilities of the
609 \section2 Generating a Calendar
611 Rich text can be generated very quickly using the cursor-based
612 approach. The following example shows a simple calendar in a
613 QTextEdit widget with bold headers for the days of the week:
615 \snippet textdocument-blocks/mainwindow.cpp 0
617 \snippet textdocument-blocks/mainwindow.cpp 1
618 \snippet textdocument-blocks/mainwindow.cpp 2
619 \snippet textdocument-blocks/mainwindow.cpp 3
621 The above example demonstrates how simple it is to quickly generate new
622 rich text documents using a minimum amount of code. Although we have
623 generated a crude fixed-pitch calendar to avoid quoting too much code,
624 Scribe provides much more sophisticated layout and formatting features.
628 \page richtext-layouts.html
629 \previouspage The QTextCursor Interface
630 \nextpage Common Rich Text Editing Tasks
632 \title Document Layouts
636 The layout of a document is only relevant when it is to be displayed on
637 a device, or when some information is requested that requires a visual
638 representation of the document. Until this occurs, the document does
639 not need to be formatted and prepared for a device.
643 Each document's layout is managed by a subclass of the
644 QAbstractTextDocumentLayout class. This class provides a common
645 interface for layout and rendering engines. The default rendering
646 behavior is currently implemented in a private class. This approach
647 makes it possible to create custom layouts, and provides the
648 mechanism used when preparing pages for printing or exporting to
649 Portable Document Format (PDF) files.
651 \section1 Example - Shaped Text Layout
653 Sometimes it is important to be able to format plain text within an
654 irregularly-shaped region, perhaps when rendering a custom widget, for
655 example. Scribe provides generic features, such as those provided by
656 the QTextLayout class, to help developers perform word-wrapping and
657 layout tasks without the need to create a document first.
659 \image plaintext-layout.png
661 Formatting and drawing a paragraph of plain text is straightforward.
662 The example below will lay out a paragraph of text, using a single
663 font, around the right hand edge of a circle.
665 \snippet plaintextlayout/window.cpp 0
667 We create a text layout, specifying the text string we want to display
668 and the font to use. We ensure that the text we supplied is formatted
669 correctly by obtaining text lines from the text format, and wrapping
670 the remaining text using the available space. The lines are positioned
671 as we move down the page.
673 The formatted text can be drawn onto a paint device; in the above code,
674 the text is drawn directly onto a widget.
678 \page richtext-common-tasks.html
679 \previouspage Document Layouts
680 \nextpage Advanced Rich Text Processing
682 \title Common Rich Text Editing Tasks
686 There are a number of tasks that are often performed by developers
687 when editing and processing text documents using Qt. These include the use
688 of display widgets such as QTextBrowser and QTextEdit, creation of
689 documents with QTextDocument, editing using a QTextCursor, and
690 exporting the document structure.
691 This document outlines some of the more common ways of using the rich
692 text classes to perform these tasks, showing convenient patterns that can
693 be reused in your own applications.
695 \section1 Using QTextEdit
697 A text editor widget can be constructed and used to display HTML in the
700 \snippet code/doc_src_richtext.cpp 2
702 By default, the text editor contains a document with a root frame, inside
703 which is an empty text block. This document can be obtained so that it can
704 be modified directly by the application:
706 \snippet code/doc_src_richtext.cpp 3
708 The text editor's cursor may also be used to edit a document:
710 \snippet code/doc_src_richtext.cpp 4
712 Although a document can be edited using many cursors at once, a QTextEdit
713 only displays a single cursor at a time. Therefore, if we want to update the
714 editor to display a particular cursor or its selection, we need to set the
715 editor's cursor after we have modified the document:
717 \snippet code/doc_src_richtext.cpp 5
719 \section1 Selecting Text
721 Text is selected by moving the cursor using operations that are similar to
722 those performed by a user in a text editor. To select text between two
723 points in the document, we need to position the cursor at the first point
724 then move it using a special mode (\l{QTextCursor::MoveMode}) with a
725 move operation (\l{QTextCursor::MoveOperation}).
726 When we select the text, we leave the selection anchor at the old cursor
727 position just as the user might do by holding down the Shift key when
730 \snippet textdocument-selections/mainwindow.cpp 1
732 In the above code, a whole word is selected using this method. QTextCursor
733 provides a number of common move operations for selecting individual
734 characters, words, lines, and whole blocks.
736 \section1 Finding Text
738 QTextDocument provides a cursor-based interface for searching, making
739 it easy to find and modify text in the style of a text editor. The following
740 code finds all the instances of a particular word in a document, and changes
743 \snippet textdocument-find/main.cpp 0
744 \snippet textdocument-find/main.cpp 1
746 Note that the cursor does not have to be moved after each search and replace
747 operation; it is always positioned at the end of the word that was just
750 \section1 Printing Documents
752 QTextEdit is designed for the display of large rich text documents that are
753 read on screen, rendering them in the same way as a web browser. As a result,
754 it does not automatically break the contents of the document into page-sized
755 pieces that are suitable for printing.
757 QTextDocument provides a \l{QTextDocument::print()}{print()} function to
758 allow documents to be printed using the QPrinter class. The following code
759 shows how to prepare a document in a QTextEdit for printing with a QPrinter:
761 \snippet textdocument-printing/mainwindow.cpp 0
763 The document is obtained from the text editor, and a QPrinter is constructed
764 then configured using a QPrintDialog. If the user accepts the printer's
765 configuration then the document is formatted and printed using the
766 \l{QTextDocument::print()}{print()} function.
770 \page richtext-advanced-processing.html
771 \previouspage Common Rich Text Editing Tasks
772 \nextpage Supported HTML Subset
774 \title Advanced Rich Text Processing
776 \section1 Handling Large Files
778 Qt does not limit the size of files that are used for text
779 processing. In most cases, this will not present a problem. For
780 especially large files, however, you might experience that your
781 application will become unresponsive or that you will run out of
782 memory. The size of the files you can load depends on your
783 hardware and on Qt's and your own application's implementation.
785 If you are faced with this problem, we recommend that you address the
789 \li You should consider breaking up large paragraphs into smaller
790 ones as Qt handles small paragraphs better. You could also
791 insert line breaks at regular intervals, which will look the
792 same as one large paragraph in a QTextEdit.
793 \li You can reduce the amount of blocks in a QTextDocument with
794 \l{QTextDocument::}{maximumBlockCount()}. The document is only
795 as large as the number of blocks as far as QTextEdit is concerned.
796 \li When adding text to a text edit, it is an advantage to add it
797 in an edit block (see example below). The result is that the
798 text edit does not need to build the entire document structure at once.
801 We give an example of the latter technique from the list. We assume that
802 the text edit is visible.
804 \snippet code/doc_src_richtext.cpp 6
807 Ideas for other sections:
809 * Hiding QTextBlock elements.
810 * Changing the word wrapping mode in QTextEdit. Custom word wrapping?
815 \page richtext-html-subset.html
816 \title Supported HTML Subset
817 \brief Describes the support for HTML markup in text widgets.
819 \previouspage Common Rich Text Editing Tasks
821 Qt's text widgets are able to display rich text, specified using a subset of \l {http://www.w3.org/TR/html401/}{HTML 4}
822 markup. Widgets that use QTextDocument, such as QLabel and QTextEdit, are able to display
823 rich text specified in this way.
827 \section1 Using HTML Markup in Text Widgets
829 Widgets automatically detect HTML markup and display rich text accordingly. For example,
830 setting a label's \l{QLabel::}{text} property with the string \c{"<b>Hello</b> <i>Qt!</i>"}
831 will result in the label displaying text like this: \b{Hello} \e{Qt!}
833 When HTML markup is used for text, Qt follows the rules defined by the \l{http://www.w3.org/TR/html401/}{HTML 4}
834 specification. This includes default properties for text layout, such as the
835 direction of the text flow (left-to-right) which can be changed by applying the
836 \l{#Block Attributes}{\c dir} attribute to blocks of text.
838 \section1 Supported Tags
840 The following table lists the HTML tags supported by Qt's
841 \l{Rich Text Processing}{rich text} engine.
843 \note The functionality implemented for tags listed below is a subset of
844 the full HTML 4 specification. Not all attributes are supported,
845 see comments for each tag.
853 \li Supports the \c href and \c name attributes.
863 \row \li \c blockquote
864 \li Indented paragraph
868 \li Supports the \c bgcolor attribute, which
869 can be a Qt \l{QColor::setNamedColor()}{color name}
870 or a \c #RRGGBB color specification.
875 \li Centered paragraph
890 \li Document division
891 \li Supports the standard \l{block attributes}.
894 \li Supports the standard \l{block attributes}.
897 \li Supports the standard \l{block attributes}.
902 \li Font size, family, and/or color
903 \li Supports the following attributes:
904 \c size, \c face, and \c color (Qt
905 \l{QColor::setNamedColor()}{color names} or
909 \li Supports the standard \l{block attributes}.
912 \li Supports the standard \l{block attributes}.
915 \li Supports the standard \l{block attributes}.
918 \li Supports the standard \l{block attributes}.
921 \li Supports the standard \l{block attributes}.
924 \li Supports the standard \l{block attributes}.
930 \li Supports the \c width attribute, which can
931 be specified as an absolute or relative (\c %) value.
940 \li Supports the \c src, \c source
941 (for Qt 3 compatibility), \c width, and \c height
944 \li User-entered text
948 \li If a text encoding is specified using the \c{meta}
949 tag, it is picked up by Qt::codecForHtml(). Likewise,
950 if an encoding is specified to QTextDocument::toHtml(),
951 the encoding is stored using a \c meta tag, for
953 \c {<meta http-equiv="Content-Type" content="text/html; charset=EUC-JP" />}
958 \li Non-breakable text
962 \li Supports the standard \l{list attributes}.
965 \li Left-aligned by default. Supports the standard
966 \l{block attributes}.
971 \li Qt rich-text document
972 \li Synonym for \c html. Provided for compatibility with
973 earlier versions of Qt.
997 \li Supports the following attributes: \c border,
998 \c bgcolor (Qt \l{QColor::setNamedColor()}{color names}
999 or \c #RRGGBB), \c cellspacing, \c cellpadding,
1000 \c width (absolute or relative), and \c height.
1006 \li Supports the standard \l{table cell attributes}.
1011 \li Table header cell
1012 \li Supports the standard \l{table cell attributes}.
1015 \li If the \c thead tag is specified, it is used when printing tables
1016 that span multiple pages.
1019 \li The value specified using the \c
1020 title tag is available through
1021 QTextDocument::metaInformation().
1024 \li Supports the \c bgcolor attribute, which
1025 can be a Qt \l{QColor::setNamedColor()}{color name}
1026 or a \c #RRGGBB color specification.
1035 \li Supports the standard \l{list attributes}.
1041 \section1 Block Attributes
1043 The following attributes are supported by the \c div, \c dl, \c
1044 dt, \c h1, \c h2, \c h3, \c h4, \c h5, \c h6, \c p tags:
1047 \li \c align (\c left, \c right, \c center, \c justify)
1048 \li \c dir (\c ltr, \c rtl)
1051 \section1 List Attributes
1053 The following attribute is supported by the \c ol and \c ul tags:
1056 \li \c type (\c 1, \c a, \c A, \c square, \c disc, \c circle)
1059 \section1 Table Cell Attributes
1061 The following attributes are supported by the \c td and \c th
1065 \li \c width (absolute, relative, or no-value)
1066 \li \c bgcolor (Qt \l{QColor::setNamedColor()}{color names} or \c #RRGGBB)
1069 \li \c align (\c left, \c right, \c center, \c justify)
1070 \li \c valign (\c top, \c middle, \c bottom)
1073 \section1 CSS Properties
1074 The following table lists the CSS properties supported by Qt's
1075 \l{Rich Text Processing}{rich text} engine:
1078 \header \li Property
1082 \li \c background-color
1084 \li Background color for elements
1086 \li \c background-image
1088 \li Background image for elements
1091 \li Text foreground color
1092 \row \li \c font-family
1094 \li Font family name
1095 \row \li \c font-size
1096 \li [ small | medium | large | x-large | xx-large ] | <size>pt | <size>px
1097 \li Font size relative to the document font, or specified in points or pixels
1098 \row \li \c font-style
1099 \li [ normal | italic | oblique ]
1101 \row \li \c font-weight
1102 \li [ normal | bold | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 ]
1103 \li Specifies the font weight used for text, where \c normal and \c bold
1104 are mapped to the corresponding QFont weights. Numeric values are
1105 8 times the equivalent QFont weight values.
1106 \row \li \c text-decoration
1107 \li none | [ underline || overline || line-through ]
1108 \li Additional text effects
1110 \li [ [ <'font-style'> || <'font-weight'> ]? <'font-size'> <'font-family'> ]
1111 \li Font shorthand property
1112 \row \li \c text-indent
1114 \li First line text indentation in pixels
1115 \row \li \c white-space
1116 \li normal | pre | nowrap | pre-wrap
1117 \li Declares how whitespace in HTML is handled.
1118 \row \li \c margin-top
1120 \li Top paragraph margin in pixels
1121 \row \li \c margin-bottom
1123 \li Bottom paragraph margin in pixels
1124 \row \li \c margin-left
1126 \li Left paragraph margin in pixels
1127 \row \li \c margin-right
1129 \li Right paragraph margin in pixels
1130 \row \li \c padding-top
1132 \li Top table cell padding in pixels
1133 \row \li \c padding-bottom
1135 \li Bottom table cell padding in pixels
1136 \row \li \c padding-left
1138 \li Left table cell padding in pixels
1139 \row \li \c padding-right
1141 \li Right table cell padding in pixels
1144 \li Shorthand for setting all the padding properties at once.
1145 \row \li \c vertical-align
1146 \li baseline | sub | super | middle | top | bottom
1147 \li Vertical text alignment. For vertical alignment in text table cells only middle, top, and bottom apply.
1148 \row \li \c border-collapse
1149 \li collapse | separate
1150 \li Border Collapse mode for text tables. If set to collapse, cell-spacing will not be applied.
1151 \row \li \c border-color
1153 \li Border color for text tables and table cells.
1154 \row \li \c border-top-color
1156 \li Top border color for table cells.
1157 \row \li \c border-bottom-color
1159 \li Bottom border color for table cells.
1160 \row \li \c border-left-color
1162 \li Left border color for table cells.
1163 \row \li \c border-right-color
1165 \li Right border color for table cells.
1166 \row \li \c border-style
1167 \li none | dotted | dashed | dot-dash | dot-dot-dash | solid | double | groove | ridge | inset | outset
1168 \li Border style for text tables and table cells.
1169 \row \li \c border-top-style
1171 \li Top border style for table cells.
1172 \row \li \c border-bottom-style
1174 \li Bottom border style for table cells.
1175 \row \li \c border-left-style
1177 \li Left border style for table cells.
1178 \row \li \c border-right-style
1180 \li Right border style for table cells.
1181 \row \li \c border-width
1183 \li Width of table or cell border
1184 \row \li \c border-top-width
1186 \li Top border width for table cells.
1187 \row \li \c border-bottom-width
1189 \li Bottom border width for table cells.
1190 \row \li \c border-left-width
1192 \li Left border width for table cells.
1193 \row \li \c border-right-width
1195 \li Right border width for table cells.
1196 \row \li \c border-top
1197 \li <width>px <border-style> <border-color>
1198 \li Shorthand for setting top border width, style and color
1199 \row \li \c border-bottom
1200 \li <width>px <border-style> <border-color>
1201 \li Shorthand for setting bottom border width, style and color
1202 \row \li \c border-left
1203 \li <width>px <border-style> <border-color>
1204 \li Shorthand for setting left border width, style and color
1205 \row \li \c border-right
1206 \li <width>px <border-style> <border-color>
1207 \li Shorthand for setting right border width, style and color
1208 \row \li \c border-top
1209 \li <width>px <border-style> <border-color>
1210 \li Shorthand for setting top border width, style and color
1211 \row \li \c border-bottom
1212 \li <width>px <border-style> <border-color>
1213 \li Shorthand for setting bottom border width, style and color
1215 \li <width>px <border-style> <border-color>
1216 \li Shorthand for setting all four border's width, style and color
1217 \row \li \c background
1218 \li [ <'background-color'> || <'background-image'> ]
1219 \li Background shorthand property
1220 \row \li \c page-break-before
1221 \li [ auto | always ]
1222 \li Make it possible to enforce a page break before the paragraph/table
1223 \row \li \c page-break-after
1224 \li [ auto | always ]
1225 \li Make it possible to enforce a page break after the paragraph/table
1227 \li [ left | right | none ]
1228 \li Specifies where an image or a text will be placed in another element. Note that the \c float property is
1229 only supported for tables and images.
1230 \row \li \c text-transform
1231 \li [ uppercase | lowercase ]
1232 \li Select the transformation that will be performed on the text prior to displaying it.
1233 \row \li \c font-kerning
1234 \li [ normal | none ]
1235 \li Enables or disables kerning between text characters.
1236 \row \li \c font-variant
1238 \li Perform the smallcaps transformation on the text prior to displaying it.
1239 \row \li \c word-spacing
1241 \li Specifies an alternate spacing between each word.
1242 \row \li \c line-height
1243 \li <number>[% | px | pt | cm]
1244 \li Specifies the height of a line. It can be one of the
1247 \li fixed line height in pixels, points, or centimeters.
1248 \li a percentage of the current font size.
1252 \section1 Qt-specific CSS properties
1254 Besides the standard CSS properties listed earlier, the following
1255 Qt-specific properties can also be used to style a text block:
1258 \header \li Property
1262 \li \c -qt-block-indent
1264 \li Indents the text block by the specified no. spaces.
1266 \li \c -qt-list-indent
1268 \li Indents the list items by the specified no. of spaces.
1270 \li \c -qt-list-number-prefix
1272 \li Prefixes the given string to list number in an HTML ordered list.
1274 \li \c -qt-list-number-suffix
1276 \li Suffixes the given string to list number in an HTML ordered list.
1278 \li \c -qt-paragraph-type
1280 \li Hides the text block.
1282 \li \c -qt-table-type
1283 \li \c{root | frame}
1284 \li \c root renders the text blocks inline without borders and
1285 indentation, whereas \c frame renders them on a new line
1286 with a frame around.
1288 \li \c -qt-user-state
1290 \li Adds it as user data for the text block.
1293 \section1 Supported CSS Selectors
1295 All CSS 2.1 selector classes are supported except pseudo-class selectors such
1296 as \c{:first-child}, \c{:visited} and \c{:hover}.
1.10.0