Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
richtext.qdoc
Go to the documentation of this file.
1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \group richtext-processing
6 \brief How to use Rich Text Processing APIs.
7 \title Rich Text Processing APIs
8*/
9
10/*!
11 \page richtext.html
12 \title Rich Text Processing
13 \brief Overview of Qt's rich text processing, editing, and display features.
14 \ingroup explanations-ui
15 \ingroup frameworks-technologies
16 \ingroup qt-basic-concepts
17
18 Qt provides a set of classes for creating, editing, and rendering
19 structured rich text documents. These classes center around QTextDocument,
20 which represents a rich text document with a well-defined internal
21 structure. Working directly with QTextDocument allows applications to
22 create, modify, and inspect rich text without relying on intermediate
23 markup formats.
24
25 You can access document information via two complementary interfaces:
26
27 \table
28 \header
29 \li Interface
30 \li Description
31 \row
32 \li Cursor-based interface (QTextCursor)
33 \li Supports editing operations that mimic user actions in a text
34 editor. Edits maintain the structural integrity of the underlying
35 document.
36 \row
37 \li Read-only hierarchical interface
38 \li Provides a high-level structural view of the document. It is
39 useful for tasks such as searching, inspection, and exporting
40 content.
41 \endtable
42
43 \section1 Rich Text Serialization
44
45 QTextDocument supports serialization to and from these markup formats:
46
47 \list
48 \li HTML: A defined subset of HTML is supported for loading and saving.
49 See \l {Supported HTML Subset}.
50 \li Markdown: QTextDocument can parse Markdown in both CommonMark and
51 GitHub dialects.
52 \endlist
53
54 \section1 Rich Text Topics
55
56 \list
57 \li \l{Rich Text Document Structure} describes the different elements
58 in a QTextDocument and how they are arranged in a document
59 structure.
60 \li \l{The QTextCursor Interface} explains how to edit rich text
61 documents using the cursor-based interface.
62 \li \l{Document Layouts} describes how to visually arrange document
63 contents.
64 \li \l{Common Rich Text Editing Tasks} describes frequently used
65 operations for reading and manipulating rich text such as selecting,
66 searching, and printing.
67 \li \l{Advanced Rich Text Processing} describes advanced rich text
68 editing tasks such as handling large files.
69 \li \l{Supported HTML Subset} lists the HTML tags supported by
70 QTextDocument.
71 \endlist
72
73 \section1 Rich Text Processing APIs
74
75 Qt provides an extensive collection of classes for parsing, rendering
76 manipulating and editing rich text.
77
78 \annotatedlist richtext-processing
79*/
80
81/*!
82 \page richtext-structure.html
83 \previouspage Rich Text Processing
84 \nextpage The QTextCursor Interface
85
86 \title Rich Text Document Structure
87
88 Text documents are represented by the QTextDocument class, which
89 contains information about the document's internal representation, its
90 structure, and keeps track of modifications to provide undo/redo
91 facilities.
92
93 The structured representation of a text document presents its contents as
94 a hierarchy of text blocks, frames, tables, and other objects. These provide
95 a logical structure to the document and describe how their contents will be
96 displayed. Generally, frames and tables are used to group other
97 structures while text blocks contain the actual textual information.
98
99 New elements are created and inserted into the document programmatically
100 \l{richtext-cursor.html}{with a QTextCursor} or by using an editor
101 widget, such as QTextEdit. Elements can be given a particular format when
102 they are created; otherwise they take the cursor's current format for the
103 element.
104
105 \table
106 \row
107 \li \inlineimage richtext-document.png
108 {Document structure with frames and text blocks}
109 \li \b{Basic structure}
110
111 The "top level" of a document might be populated in the way shown.
112 Each document always contains a root frame, and this always contains
113 at least one text block.
114
115 For documents with some textual content, the root
116 frame usually contains a sequence of blocks and other elements.
117
118 Sequences of frames and tables are always separated by text blocks in a
119 document, even if the text blocks contain no information. This ensures that
120 new elements can always be inserted between existing structures.
121 \endtable
122
123 In this chapter, we look at each of the structural elements
124 used in a rich text document, outline their features and uses, and show
125 how to examine their contents. Document editing is described in
126 \l{richtext-cursor.html}{The QTextCursor Interface}.
127
128 \section1 Rich Text Documents
129
130 QTextDocument objects contain all the information required to construct
131 rich text documents.
132 Text documents can be accessed in two complementary ways: as a linear
133 buffer for editors to use, and as an object hierarchy that is useful to
134 layout engines.
135 In the hierarchical document model, objects generally correspond to
136 visual elements such as frames, tables, and lists. At a lower level,
137 these elements describe properties such as the text style and alignment.
138 The linear representation of the document is used for editing and
139 manipulation of the document's contents.
140
141 Although QTextEdit makes it easy to display and edit rich text, documents
142 can also be used independently of any editor widget, for example:
143
144 \snippet code/doc_src_richtext.cpp 0
145
146 Alternatively, they can be extracted from an existing editor:
147
148 \snippet code/doc_src_richtext.cpp 1
149
150 This flexibility enables applications to handle multiple rich text
151 documents without the overhead of multiple editor widgets, or requiring
152 documents to be stored in some intermediate format.
153
154 An empty document contains a root frame which itself contains a single
155 empty text block. Frames provide logical separation between parts of the document, but
156 also have properties that determine how they will appear when rendered.
157 A table is a specialized type of frame that consists of a number of
158 cells, arranged into rows and columns, each of which can contain
159 further structure and text. Tables provide management and layout
160 features that allow flexible configurations of cells to be created.
161
162 Text blocks contain text fragments, each of which specifies text and
163 character format information. Textual properties are defined both at
164 the character level and at the block level. At the character level,
165 properties such as font family, text color, and font weight can be
166 specified. The block level properties control the higher level
167 appearance and behavior of the text, such as the direction of text
168 flow, alignment, and background color.
169
170 The document structure is not manipulated directly. Editing is
171 performed through a cursor-based interface.
172 The \l{richtext-cursor.html}{text cursor interface}
173 automatically inserts new document elements into the root frame, and
174 ensures that it is padded with empty blocks where necessary.
175
176 We obtain the root frame in the following manner:
177
178 \snippet textdocument-frames/mainwindow.cpp rootframe
179
180 When navigating the document structure, it is useful to begin at the
181 root frame because it provides access to the entire document structure.
182
183
184 \section1 Document Elements
185
186 Rich text documents usually consist of common elements such as paragraphs,
187 frames, tables, and lists. These are represented in a QTextDocument
188 by the QTextBlock, QTextFrame, QTextTable, and QTextList classes.
189 Unlike the other elements in a document, images are represented by
190 specially formatted text fragments. This enables them to be placed
191 formatted inline with the surrounding text.
192
193 The basic structural building blocks in documents are QTextBlock and
194 QTextFrame. Blocks themselves contain fragments of rich text
195 (QTextFragment), but these do not directly influence the high level
196 structure of a document.
197
198 Elements which can group together other document elements are typically
199 subclasses of QTextObject, and fall into two categories: Elements that
200 group together text blocks are subclasses of QTextBlockGroup, and those
201 that group together frames and other elements are subclasses of QTextFrame.
202
203 \section2 Text Blocks
204
205 Text blocks are provided by the QTextBlock class.
206
207 Text blocks group together fragments of text with different character formats,
208 and are used to represent paragraphs in the document. Each block
209 typically contains a number of text fragments with different styles.
210 Fragments are created when text is inserted into the document, and more
211 of them are added when the document is edited. The document splits, merges,
212 and removes fragments to efficiently represent the different styles
213 of text in the block.
214
215 The fragments within a given block can be examined by using a
216 QTextBlock::iterator to traverse the block's internal structure:
217
218 \snippet textblock-fragments/xmlwriter.cpp 3
219 \snippet textblock-fragments/xmlwriter.cpp 5
220 \snippet textblock-fragments/xmlwriter.cpp 6
221
222 Blocks are also used to represent list items. As a result, blocks can
223 define their own character formats which contain information about
224 block-level decoration, such as the type of bullet points used for
225 list items. The formatting for the block itself is described by the
226 QTextBlockFormat class, and describes properties such as text alignment,
227 indentation, and background color.
228
229 Although a given document may contain complex structures, once we have a
230 reference to a valid block in the document, we can navigate between each
231 of the text blocks in the order in which they were written:
232
233 \snippet textblock-fragments/xmlwriter.cpp 0
234 \snippet textblock-fragments/xmlwriter.cpp 1
235 \snippet textblock-fragments/xmlwriter.cpp 2
236
237 This method is useful for when you want to extract just the rich text from a
238 document because it ignores frames, tables, and other types of structure.
239
240 QTextBlock provides comparison operators that make it easier to manipulate
241 blocks: \l{QTextBlock::operator==()}{operator==()} and
242 \l{QTextBlock::operator!=()}{operator!=()} are used to test whether two
243 blocks are the same, and \l{QTextBlock::operator<()}{operator<()} is used
244 to determine which one occurs first in a document.
245
246 \section2 Frames
247
248 Frames are provided by the QTextFrame class.
249
250 Text frames group together blocks of text and child frames, creating
251 document structures that are larger than paragraphs. The format of a frame
252 specifies how it is rendered and positioned on the page. Frames are
253 either inserted into the text flow, or they float on the left or right
254 hand side of the page.
255 Each document contains a root frame that contains all the other document
256 elements. As a result, all frames except the root frame have a parent
257 frame.
258
259 Since text blocks are used to separate other document elements, each
260 frame will always contain at least one text block, and zero or more
261 child frames. We can inspect the contents of a frame by using a
262 QTextFrame::iterator to traverse the frame's child elements:
263
264 \snippet textdocument-frames/mainwindow.cpp 4
265
266 Note that the iterator selects both frames and blocks, so it is necessary
267 to check which it is referring to. This allows us to navigate the document
268 structure on a frame-by-frame basis yet still access text blocks if
269 required. Both the QTextBlock::iterator and QTextFrame::iterator classes
270 can be used in complementary ways to extract the required structure from
271 a document.
272
273 \section2 Tables
274
275 Tables are provided by the QTextTable class.
276
277 Tables are collections of cells that are arranged in rows and columns.
278 Each table cell is a document element with its own character format, but it
279 can also contain other elements, such as frames and text blocks. Table cells
280 are automatically created when the table is constructed, or when extra rows
281 or columns are added. They can also be moved between tables.
282
283 QTextTable is a subclass of QTextFrame, so tables are treated like frames
284 in the document structure. For each frame that we encounter in the
285 document, we can test whether it represents a table, and deal with it in a
286 different way:
287
288 \snippet textdocument-tables/mainwindow.cpp 13
289
290 The cells within an existing table can be examined by iterating through
291 the rows and columns.
292
293 \snippet textdocument-tables/mainwindow.cpp 9
294 \snippet textdocument-tables/mainwindow.cpp 10
295 \snippet textdocument-tables/mainwindow.cpp 11
296 \snippet textdocument-tables/mainwindow.cpp 12
297
298
299 \section2 Lists
300
301 Lists are provided by the QTextList class.
302
303 Lists are sequences of text blocks that are formatted in the usual way, but
304 which also provide the standard list decorations such as bullet points and
305 enumerated items. Lists can be nested, and will be indented if the list's
306 format specifies a non-zero indentation.
307
308 We can refer to each list item by its index in the list:
309
310 \snippet textdocument-listitems/mainwindow.cpp 0
311 \snippet textdocument-listitems/mainwindow.cpp 1
312 \snippet textdocument-listitems/mainwindow.cpp 2
313
314 Since QTextList is a subclass of QTextBlockGroup, it does not group the
315 list items as child elements, but instead provides various functions for
316 managing them. This means that any text block we find when traversing a
317 document may actually be a list item. We can ensure that list items are
318 correctly identified by using the following code:
319
320 \snippet textdocument-listitems/mainwindow.cpp 3
321 \snippet textdocument-listitems/mainwindow.cpp 4
322 \snippet textdocument-listitems/mainwindow.cpp 5
323 \snippet textdocument-listitems/mainwindow.cpp 6
324 \snippet textdocument-listitems/mainwindow.cpp 7
325
326
327 \section2 Images
328
329 Images in QTextDocument are represented by text fragments that reference
330 external images via the resource mechanism. Images are created using the
331 cursor interface, and can be modified later by changing the character
332 format of the image's text fragment:
333
334 \snippet textdocument-imageformat/main.cpp 0
335 \snippet textdocument-imageformat/main.cpp 1
336 \snippet textdocument-imageformat/main.cpp 2
337
338 The fragment that represents the image can be found by iterating over
339 the fragments in the text block that contains the image.
340*/
341
342/*!
343 \page richtext-cursor.html
344 \previouspage Rich Text Document Structure
345 \nextpage Document Layouts
346
347 \title The QTextCursor Interface
348
349 Documents can be edited via the interface provided by the QTextCursor
350 class; cursors are either created using a constructor or obtained from
351 an editor widget. The cursor is used to perform editing operations that
352 correspond exactly to those the user is able to make themselves in an
353 editor. As a result, information about the document structure is also
354 available through the cursor, and this allows the structure to be
355 modified. The use of a cursor-oriented interface for editing makes the
356 process of writing a custom editor simpler for developers, since the
357 editing operations can be easily visualized.
358
359 The QTextCursor class also maintains information about any text it
360 has selected in the document, again following a model that is
361 conceptually similar to the actions made by the user to select text
362 in an editor.
363
364 Rich text documents can have multiple cursors
365 associated with them, and each of these contains information about their
366 position in the document and any selections that they may hold. This
367 cursor-based paradigm makes common operations, such as cutting and pasting
368 text, simple to implement programmatically, yet it also allows more complex
369 editing operations to be performed on the document.
370
371 This chapter describes most of the common editing operations that you
372 will need to perform using a cursor, from basic insertion of text and
373 document elements to more complex manipulation of document structures.
374
375 \section1 Cursor-Based Editing
376
377 At the simplest level, text documents are made up of a string of characters,
378 marked up in some way to represent the block structure of the text within the
379 document. QTextCursor provides a cursor-based interface that allows the
380 contents of a QTextDocument to be manipulated at the character level. Since
381 the elements (blocks, frames, tables, etc.) are also encoded in the character
382 stream, the document structure can itself be changed by the cursor.
383
384 The cursor keeps track of its location within its parent document, and can
385 report information about the surrounding structure, such as the enclosing
386 text block, frame, table, or list. The formats of the enclosing structures
387 can also be directly obtained through the cursor.
388
389 \section2 Using a Cursor
390
391 The main use of a cursor is to insert or modify text within a block.
392 We can use a text editor's cursor to do this:
393
394 \snippet textblock-formats/main.cpp 0
395
396 Alternatively, we can obtain a cursor directly from a document:
397
398 \snippet textdocument-images/main.cpp 0
399
400 The cursor is positioned at the start of the document so that we can write
401 into the first (empty) block in the document.
402
403 \section2 Grouping Cursor Operations
404
405 A series of editing operations can be packaged together so that they can
406 be replayed, or undone together in a single action. This is achieved by
407 using the \c beginEditBlock() and \c endEditBlock() functions in the
408 following way, as in the following example where we select the word that
409 contains the cursor:
410
411 \snippet textdocument-selections/mainwindow.cpp 0
412
413 If editing operations are not grouped, the document automatically records
414 the individual operations so that they can be undone later. Grouping
415 operations into larger packages can make editing more efficient both for
416 the user and for the application, but care has to be taken not to group too
417 many operations together as the user may want find-grained control over the
418 undo process.
419
420 \section2 Multiple Cursors
421
422 Multiple cursors can be used to simultaneously edit the same document,
423 although only one will be visible to the user in a QTextEdit widget.
424 The QTextDocument ensures that each cursor writes text correctly and
425 does not interfere with any of the others.
426
427 \omit
428 \snippet textdocument-cursors/main.cpp 0
429 \snippet textdocument-cursors/main.cpp 1
430 \endomit
431
432 \section1 Inserting Document Elements
433
434 QTextCursor provides several functions that can be used to change the
435 structure of a rich text document. Generally, these functions allow
436 document elements to be created with relevant formatting information,
437 and they are inserted into the document at the cursor's position.
438
439 The first group of functions insert block-level elements, and update the
440 cursor position, but they do not return the element that was inserted:
441
442 \list
443 \li \l{QTextCursor::insertBlock()}{insertBlock()} inserts a new text block
444 (paragraph) into a document at the cursor's position, and moves the
445 cursor to the start of the new block.
446 \li \l{QTextCursor::insertFragment()}{insertFragment()} inserts an existing
447 text fragment into a document at the cursor's position.
448 \li \l{QTextCursor::insertImage()}{insertImage()} inserts an image into a
449 document at the cursor's position.
450 \li \l{QTextCursor::insertText()}{insertText()} inserts text into the
451 document at the cursor's position.
452 \endlist
453
454 You can examine the contents of the element that was inserted through the
455 cursor interface.
456
457 The second group of functions insert elements that provide structure to
458 the document, and return the structure that was inserted:
459
460 \list
461 \li \l{QTextCursor::insertFrame()}{insertFrame()} inserts a frame into the
462 document \e after the cursor's current block, and moves the cursor to
463 the start of the empty block in the new frame.
464 \li \l{QTextCursor::insertList()}{insertList()} inserts a list into the
465 document at the cursor's position, and moves the cursor to the start
466 of the first item in the list.
467 \li \l{QTextCursor::insertTable()}{insertTable()} inserts a table into
468 the document \e after the cursor's current block, and moves the cursor
469 to the start of the block following the table.
470 \endlist
471
472 These elements either contain or group together other elements in the
473 document.
474
475 \section2 Text and Text Fragments
476
477 Text can be inserted into the current block in the current character
478 format, or in a custom format that is specified with the text:
479
480 \snippet textdocument-charformats/main.cpp 0
481
482 Once the character format has been used with a cursor, that format becomes
483 the default format for any text inserted with that cursor until another
484 character format is specified.
485
486 If a cursor is used to insert text without specifying a character format,
487 the text will be given the character format used at that position in the
488 document.
489
490 \section2 Blocks
491
492 Text blocks are inserted into the document with the
493 \l{QTextCursor::insertBlock()}{insertBlock()} function.
494
495 \snippet textblock-formats/main.cpp 1
496
497 The cursor is positioned at the start of the new block.
498
499 \section2 Frames
500
501 Frames are inserted into a document using the cursor, and will be placed
502 within the cursor's current frame \e after the current block.
503 The following code shows how a frame can be inserted between two text
504 blocks in a document's root frame. We begin by finding the cursor's
505 current frame:
506
507 \snippet textdocument-frames/mainwindow.cpp 0
508
509 We insert some text in this frame then set up a frame format for the
510 child frame:
511
512 \snippet textdocument-frames/mainwindow.cpp 1
513
514 The frame format will give the frame an external margin of 32 pixels,
515 internal padding of 8 pixels, and a border that is 4 pixels wide.
516 See the QTextFrameFormat documentation for more information about
517 frame formats.
518
519 The frame is inserted into the document after the preceding text:
520
521 \snippet textdocument-frames/mainwindow.cpp 2
522
523 We add some text to the document immediately after we insert the frame.
524 Since the text cursor is positioned \e{inside the frame} when it is inserted
525 into the document, this text will also be inserted inside the frame.
526
527 Finally, we position the cursor outside the frame by taking the last
528 available cursor position inside the frame we recorded earlier:
529
530 \snippet textdocument-frames/mainwindow.cpp 3
531
532 The text that we add last is inserted after the child frame in the
533 document. Since each frame is padded with text blocks, this ensures that
534 more elements can always be inserted with a cursor.
535
536 \section2 Tables
537
538 Tables are inserted into the document using the cursor, and will be
539 placed within the cursor's current frame \e after the current block:
540
541 \snippet textdocument-tables/mainwindow.cpp 0
542 \snippet textdocument-tables/mainwindow.cpp 3
543
544 Tables can be created with a specific format that defines the overall
545 properties of the table, such as its alignment, background color, and
546 the cell spacing used. It can also determine the constraints on each
547 column, allowing each of them to have a fixed width, or resize according
548 to the available space.
549
550 \snippet textdocument-tables/mainwindow.cpp 2
551
552 The columns in the table created above will each take up a certain
553 percentage of the available width. Note that the table format is
554 optional; if you insert a table without a format, some sensible
555 default values will be used for the table's properties.
556
557 Since cells can contain other document elements, they too can be
558 formatted and styled as necessary.
559
560 Text can be added to the table by navigating to each cell with the cursor
561 and inserting text.
562
563 \snippet textdocument-tables/mainwindow.cpp 4
564
565 We can create a simple timetable by following this approach:
566
567 \snippet textdocument-tables/mainwindow.cpp 5
568 \snippet textdocument-tables/mainwindow.cpp 6
569 \snippet textdocument-tables/mainwindow.cpp 7
570 \snippet textdocument-tables/mainwindow.cpp 8
571
572 \section2 Lists
573
574 Lists of block elements can be automatically created and inserted into the
575 document at the current cursor position. Each list that is created in this
576 way requires a list format to be specified:
577
578 \snippet textdocument-lists/mainwindow.cpp 0
579
580 The above code first checks whether the cursor is within an existing list
581 and, if so, gives the list format for the new list a suitable level of
582 indentation. This allows nested lists to be created with increasing
583 levels of indentation. A more sophisticated implementation would also use
584 different kinds of symbol for the bullet points in each level of the list.
585
586 \section2 Images
587
588 Inline images are added to documents through the cursor in the usual manner.
589 Unlike many other elements, all of the image properties are specified by the
590 image's format. This means that a QTextImageFormat object has to be
591 created before an image can be inserted:
592
593 \snippet textdocument-images/main.cpp 1
594
595 The image name refers to an entry in the application's resource file.
596 The method used to derive this name is described in
597 \l{resources.html}{The Qt Resource System}.
598
599 \section1 Examples
600
601 Rich text is stored in text documents that can either be created by
602 importing HTML from an external source, or generated using a QTextCursor.
603
604 \section2 Manipulating Rich Text
605
606 The easiest way to use a rich text document is through
607 the QTextEdit class, providing an editable view onto a document. The code
608 below imports HTML into a document, and displays the document using a
609 text edit widget.
610
611 \snippet scribe-overview/main.cpp 1
612
613 You can retrieve the document from the text edit using the
614 document() function. The document can then be edited programmatically
615 using the QTextCursor class. This class is modeled after a screen
616 cursor, and editing operations follow the same semantics. The following
617 code changes the first line of the document to a bold font, leaving all
618 other font properties untouched. The editor will be automatically
619 updated to reflect the changes made to the underlying document data.
620
621 \snippet scribe-overview/main.cpp 0
622
623 Note that the cursor was moved from the start of the first line to the
624 end, but that it retained an anchor at the start of the line. This
625 demonstrates the cursor-based selection facilities of the
626 QTextCursor class.
627
628 \section2 Generating a Calendar
629
630 Rich text can be generated very quickly using the cursor-based
631 approach. The following example shows a simple calendar in a
632 QTextEdit widget with bold headers for the days of the week:
633
634 \snippet textdocument-blocks/mainwindow.cpp 0
635 \codeline
636 \snippet textdocument-blocks/mainwindow.cpp 1
637 \snippet textdocument-blocks/mainwindow.cpp 2
638 \snippet textdocument-blocks/mainwindow.cpp 3
639
640 The above example demonstrates how simple it is to quickly generate new
641 rich text documents using a minimum amount of code. Although we have
642 generated a crude fixed-pitch calendar to avoid quoting too much code,
643 Scribe provides much more sophisticated layout and formatting features.
644*/
645
646/*!
647 \page richtext-layouts.html
648 \previouspage The QTextCursor Interface
649 \nextpage Common Rich Text Editing Tasks
650
651 \title Document Layouts
652
653 The layout of a document is only relevant when it is to be displayed on
654 a device, or when some information is requested that requires a visual
655 representation of the document. Until this occurs, the document does
656 not need to be formatted and prepared for a device.
657
658 \section1 Overview
659
660 Each document's layout is managed by a subclass of the
661 QAbstractTextDocumentLayout class. This class provides a common
662 interface for layout and rendering engines. The default rendering
663 behavior is currently implemented in a private class. This approach
664 makes it possible to create custom layouts, and provides the
665 mechanism used when preparing pages for printing or exporting to
666 Portable Document Format (PDF) files.
667
668 \section1 Example - Shaped Text Layout
669
670 Sometimes it is important to be able to format plain text within an
671 irregularly-shaped region, perhaps when rendering a custom widget, for
672 example. Scribe provides generic features, such as those provided by
673 the QTextLayout class, to help developers perform word-wrapping and
674 layout tasks without the need to create a document first.
675
676 \image plaintext-layout.webp {Screenshot of a text that flows around a
677 circle.}
678
679 Formatting and drawing a paragraph of plain text is straightforward.
680 The example below will lay out a paragraph of text, using a single
681 font, around the right hand edge of a circle.
682
683 \snippet plaintextlayout/window.cpp 0
684
685 We create a text layout, specifying the text string we want to display
686 and the font to use. We ensure that the text we supplied is formatted
687 correctly by obtaining text lines from the text format, and wrapping
688 the remaining text using the available space. The lines are positioned
689 as we move down the page.
690
691 The formatted text can be drawn onto a paint device; in the above code,
692 the text is drawn directly onto a widget.
693 */
694
695 /*!
696 \page richtext-common-tasks.html
697 \previouspage Document Layouts
698 \nextpage Advanced Rich Text Processing
699
700 \title Common Rich Text Editing Tasks
701
702 There are a number of tasks that are often performed by developers
703 when editing and processing text documents using Qt. These include the use
704 of display widgets such as QTextBrowser and QTextEdit, creation of
705 documents with QTextDocument, editing using a QTextCursor, and
706 exporting the document structure.
707 This document outlines some of the more common ways of using the rich
708 text classes to perform these tasks, showing convenient patterns that can
709 be reused in your own applications.
710
711 \section1 Using QTextEdit
712
713 A text editor widget can be constructed and used to display HTML in the
714 following way:
715
716 \snippet code/doc_src_richtext.cpp 2
717
718 By default, the text editor contains a document with a root frame, inside
719 which is an empty text block. This document can be obtained so that it can
720 be modified directly by the application:
721
722 \snippet code/doc_src_richtext.cpp 3
723
724 The text editor's cursor may also be used to edit a document:
725
726 \snippet code/doc_src_richtext.cpp 4
727
728 Although a document can be edited using many cursors at once, a QTextEdit
729 only displays a single cursor at a time. Therefore, if we want to update the
730 editor to display a particular cursor or its selection, we need to set the
731 editor's cursor after we have modified the document:
732
733 \snippet code/doc_src_richtext.cpp 5
734
735 \section1 Selecting Text
736
737 Text is selected by moving the cursor using operations that are similar to
738 those performed by a user in a text editor. To select text between two
739 points in the document, we need to position the cursor at the first point
740 then move it using a special mode (\l{QTextCursor::MoveMode}) with a
741 move operation (\l{QTextCursor::MoveOperation}).
742 When we select the text, we leave the selection anchor at the old cursor
743 position just as the user might do by holding down the Shift key when
744 selecting text:
745
746 \snippet textdocument-selections/mainwindow.cpp 1
747
748 In the above code, a whole word is selected using this method. QTextCursor
749 provides a number of common move operations for selecting individual
750 characters, words, lines, and whole blocks.
751
752 \section1 Finding Text
753
754 QTextDocument provides a cursor-based interface for searching, making
755 it easy to find and modify text in the style of a text editor. The following
756 code finds all the instances of a particular word in a document, and changes
757 the color of each:
758
759 \snippet textdocument-find/main.cpp 0
760 \snippet textdocument-find/main.cpp 1
761
762 Note that the cursor does not have to be moved after each search and replace
763 operation; it is always positioned at the end of the word that was just
764 replaced.
765
766 \section1 Printing Documents
767
768 QTextEdit is designed for the display of large rich text documents that are
769 read on screen, rendering them in the same way as a web browser. As a result,
770 it does not automatically break the contents of the document into page-sized
771 pieces that are suitable for printing.
772
773 QTextDocument provides a \l{QTextDocument::print()}{print()} function to
774 allow documents to be printed using the QPrinter class. The following code
775 shows how to prepare a document in a QTextEdit for printing with a QPrinter:
776
777 \snippet textdocument-printing/mainwindow.cpp 0
778
779 The document is obtained from the text editor, and a QPrinter is constructed
780 then configured using a QPrintDialog. If the user accepts the printer's
781 configuration then the document is formatted and printed using the
782 \l{QTextDocument::print()}{print()} function.
783*/
784
785/*!
786 \page richtext-advanced-processing.html
787 \previouspage Common Rich Text Editing Tasks
788 \nextpage Supported HTML Subset
789
790 \title Advanced Rich Text Processing
791
792 \section1 Handling Large Files
793
794 Qt does not limit the size of files that are used for text
795 processing. In most cases, this will not present a problem. For
796 especially large files, however, you might experience that your
797 application will become unresponsive or that you will run out of
798 memory. The size of the files you can load depends on your
799 hardware and on Qt's and your own application's implementation.
800
801 If you are faced with this problem, we recommend that you address the
802 following issues:
803
804 \list
805 \li You should consider breaking up large paragraphs into smaller
806 ones as Qt handles small paragraphs better. You could also
807 insert line breaks at regular intervals, which will look the
808 same as one large paragraph in a QTextEdit.
809 \li You can reduce the amount of blocks in a QTextDocument with
810 \l{QTextDocument::}{maximumBlockCount()}. The document is only
811 as large as the number of blocks as far as QTextEdit is concerned.
812 \li When adding text to a text edit, it is an advantage to add it
813 in an edit block (see example below). The result is that the
814 text edit does not need to build the entire document structure at once.
815 \endlist
816
817 We give an example of the latter technique from the list. We assume that
818 the text edit is visible.
819
820 \snippet code/doc_src_richtext.cpp 6
821
822 \omit
823 Ideas for other sections:
824
825 * Hiding QTextBlock elements.
826 * Changing the word wrapping mode in QTextEdit. Custom word wrapping?
827 \endomit
828*/
829
830/*!
831 \page richtext-html-subset.html
832 \title Supported HTML Subset
833 \brief Describes the support for HTML markup in text widgets.
834
835 \previouspage Common Rich Text Editing Tasks
836
837 Qt's text widgets are able to display rich text, specified using a subset of \l {http://www.w3.org/TR/html401/}{HTML 4}
838 markup. Widgets that use QTextDocument, such as QLabel and QTextEdit, are able to display
839 rich text specified in this way.
840
841 \section1 Using HTML Markup in Text Widgets
842
843 Widgets automatically detect HTML markup and display rich text accordingly. For example,
844 setting a label's \l{QLabel::}{text} property with the string \c{"<b>Hello</b> <i>Qt!</i>"}
845 will result in the label displaying text like this: \b{Hello} \e{Qt!}
846
847 When HTML markup is used for text, Qt follows the rules defined by the \l{http://www.w3.org/TR/html401/}{HTML 4}
848 specification. This includes default properties for text layout, such as the
849 direction of the text flow (left-to-right) which can be changed by applying the
850 \l{#Block Attributes}{\c dir} attribute to blocks of text.
851
852 \section1 Supported Tags
853
854 The following table lists the HTML tags supported by Qt's
855 \l{Rich Text Processing}{rich text} engine.
856
857 \note The functionality implemented for tags listed below is a subset of
858 the full HTML 4 specification. Not all attributes are supported,
859 see comments for each tag.
860
861 \table 70%
862 \header \li Tag
863 \li Description
864 \li Comment
865 \row \li \c a
866 \li Anchor or link
867 \li Supports the \c href and \c name attributes.
868 \row \li \c address
869 \li Address
870 \li
871 \row \li \c b
872 \li Bold
873 \li
874 \row \li \c big
875 \li Larger font
876 \li
877 \row \li \c blockquote
878 \li Indented paragraph
879 \li
880 \row \li \c body
881 \li Document body
882 \li Supports the \c bgcolor attribute, which
883 can be a Qt \l{QColor::fromString()}{color name}
884 or a \c #RRGGBB color specification.
885 \row \li \c br
886 \li Line break
887 \li
888 \row \li \c center
889 \li Centered paragraph
890 \li
891 \row \li \c cite
892 \li Inline citation
893 \li Same as \c i.
894 \row \li \c code
895 \li Code
896 \li Same as \c tt.
897 \row \li \c dd
898 \li Definition data
899 \li
900 \row \li \c del
901 \li Deleted
902 \li Same as \c s. Since Qt 6.11
903 \row \li \c dfn
904 \li Definition
905 \li Same as \c i.
906 \row \li \c div
907 \li Document division
908 \li Supports the standard \l{block attributes}.
909 \row \li \c dl
910 \li Definition list
911 \li Supports the standard \l{block attributes}.
912 \row \li \c dt
913 \li Definition term
914 \li Supports the standard \l{block attributes}.
915 \row \li \c em
916 \li Emphasized
917 \li Same as \c i.
918 \row \li \c font
919 \li Font size, family, and/or color
920 \li Supports the following attributes:
921 \c size, \c face, and \c color (Qt
922 \l{QColor::fromString()}{color names} or
923 \c #RRGGBB).
924 \row \li \c h1
925 \li Level 1 heading
926 \li Supports the standard \l{block attributes}.
927 \row \li \c h2
928 \li Level 2 heading
929 \li Supports the standard \l{block attributes}.
930 \row \li \c h3
931 \li Level 3 heading
932 \li Supports the standard \l{block attributes}.
933 \row \li \c h4
934 \li Level 4 heading
935 \li Supports the standard \l{block attributes}.
936 \row \li \c h5
937 \li Level 5 heading
938 \li Supports the standard \l{block attributes}.
939 \row \li \c h6
940 \li Level 6 heading
941 \li Supports the standard \l{block attributes}.
942 \row \li \c head
943 \li Document header
944 \li
945 \row \li \c hr
946 \li Horizontal line
947 \li Supports the \c width attribute, which can
948 be specified as an absolute or relative (\c %) value.
949 \row \li \c html
950 \li HTML document
951 \li
952 \row \li \c i
953 \li Italic
954 \li
955 \row \li \c img
956 \li Image
957 \li Supports the \c src, \c source
958 (for Qt 3 compatibility), \c width, and \c height
959 attributes.
960 \row \li \c kbd
961 \li User-entered text
962 \li
963 \row \li \c meta
964 \li Meta-information
965 \li If a text encoding is specified using the \c{meta}
966 tag, it is picked up by Qt::codecForHtml(). Likewise,
967 if an encoding is specified to QTextDocument::toHtml(),
968 the encoding is stored using a \c meta tag, for
969 example:
970 \c {<meta http-equiv="Content-Type" content="text/html; charset=EUC-JP" />}
971 \row \li \c li
972 \li List item
973 \li
974 \row \li \c nobr
975 \li Non-breakable text
976 \li
977 \row \li \c ol
978 \li Ordered list
979 \li Supports the standard \l{list attributes}.
980 \row \li \c p
981 \li Paragraph
982 \li Left-aligned by default. Supports the standard
983 \l{block attributes}.
984 \row \li \c pre
985 \li Preformated text
986 \li
987 \row \li \c qt
988 \li Qt rich-text document
989 \li Synonym for \c html. Provided for compatibility with
990 earlier versions of Qt.
991 \row \li \c s
992 \li Strikethrough
993 \li
994 \row \li \c samp
995 \li Sample code
996 \li Same as \c tt.
997 \row \li \c small
998 \li Small font
999 \li
1000 \row \li \c span
1001 \li Grouped elements
1002 \li
1003 \row \li \c strong
1004 \li Strong
1005 \li Same as \c b.
1006 \row \li \c sub
1007 \li Subscript
1008 \li
1009 \row \li \c sup
1010 \li Superscript
1011 \li
1012 \row \li \c table
1013 \li Table
1014 \li Supports the following attributes: \c border,
1015 \c bgcolor (Qt \l{QColor::fromString()}{color names}
1016 or \c #RRGGBB), \c cellspacing, \c cellpadding,
1017 \c width (absolute or relative), and \c height.
1018 \row \li \c tbody
1019 \li Table body
1020 \li Does nothing.
1021 \row \li \c td
1022 \li Table data cell
1023 \li Supports the standard \l{table cell attributes}.
1024 \row \li \c tfoot
1025 \li Table footer
1026 \li Does nothing.
1027 \row \li \c th
1028 \li Table header cell
1029 \li Supports the standard \l{table cell attributes}.
1030 \row \li \c thead
1031 \li Table header
1032 \li If the \c thead tag is specified, it is used when printing tables
1033 that span multiple pages.
1034 \row \li \c title
1035 \li Document title
1036 \li The value specified using the \c
1037 title tag is available through
1038 QTextDocument::metaInformation().
1039 \row \li \c tr
1040 \li Table row
1041 \li Supports the \c bgcolor attribute, which
1042 can be a Qt \l{QColor::fromString()}{color name}
1043 or a \c #RRGGBB color specification.
1044 \row \li \c tt
1045 \li Typewrite font
1046 \li
1047 \row \li \c u
1048 \li Underlined
1049 \li
1050 \row \li \c ul
1051 \li Unordered list
1052 \li Supports the standard \l{list attributes}.
1053 \row \li \c var
1054 \li Variable
1055 \li Same as \c i.
1056 \endtable
1057
1058 \section1 Block Attributes
1059
1060 The following attributes are supported by the \c div, \c dl, \c
1061 dt, \c h1, \c h2, \c h3, \c h4, \c h5, \c h6, \c p tags:
1062
1063 \list
1064 \li \c align (\c left, \c right, \c center, \c justify)
1065 \li \c dir (\c ltr, \c rtl)
1066 \endlist
1067
1068 \section1 List Attributes
1069
1070 The following attribute is supported by the \c ol and \c ul tags:
1071
1072 \list
1073 \li \c type (\c 1, \c a, \c A, \c square, \c disc, \c circle)
1074 \endlist
1075
1076 Additionally, the following attribute is supported by the \c ol tag:
1077
1078 \list
1079 \li \c start
1080 \endlist
1081
1082 \section1 Table Cell Attributes
1083
1084 The following attributes are supported by the \c td and \c th
1085 tags:
1086
1087 \list
1088 \li \c width (absolute, relative, or no-value)
1089 \li \c bgcolor (Qt \l{QColor::fromString()}{color names} or \c #RRGGBB)
1090 \li \c colspan
1091 \li \c rowspan
1092 \li \c align (\c left, \c right, \c center, \c justify)
1093 \li \c valign (\c top, \c middle, \c bottom)
1094 \endlist
1095
1096 \section1 CSS Properties
1097 The following table lists the CSS properties supported by Qt's
1098 \l{Rich Text Processing}{rich text} engine:
1099
1100 \table
1101 \header \li Property
1102 \li Values
1103 \li Description
1104 \row
1105 \li \c background-color
1106 \li <color>
1107 \li Background color for elements
1108 \row
1109 \li \c background-image
1110 \li <uri>
1111 \li Background image for elements
1112 \row \li \c color
1113 \li <color>
1114 \li Text foreground color
1115 \row \li \c font-family
1116 \li <family name>
1117 \li Font family name
1118 \row \li \c font-size
1119 \li [ small | medium | large | x-large | xx-large ] | <size>pt | <size>px
1120 \li Font size relative to the document font, or specified in points or pixels
1121 \row \li \c font-style
1122 \li [ normal | italic | oblique ]
1123 \li
1124 \row \li \c font-weight
1125 \li [ normal | bold | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 ]
1126 \li Specifies the font weight used for text, where \c normal and \c bold
1127 are mapped to the corresponding QFont weights. Numeric values are
1128 8 times the equivalent QFont weight values.
1129 \row \li \c text-decoration
1130 \li none | [ underline || overline || line-through ]
1131 \li Additional text effects
1132 \row \li \c font
1133 \li [ [ <'font-style'> || <'font-weight'> ]? <'font-size'> <'font-family'> ]
1134 \li Font shorthand property
1135 \row \li \c text-indent
1136 \li <length>px
1137 \li First line text indentation in pixels
1138 \row \li \c white-space
1139 \li normal | pre | nowrap | pre-wrap
1140 \li Declares how whitespace in HTML is handled.
1141 \row \li \c margin-top
1142 \li <length>px
1143 \li Top paragraph margin in pixels
1144 \row \li \c margin-bottom
1145 \li <length>px
1146 \li Bottom paragraph margin in pixels
1147 \row \li \c margin-left
1148 \li <length>px
1149 \li Left paragraph margin in pixels
1150 \row \li \c margin-right
1151 \li <length>px
1152 \li Right paragraph margin in pixels
1153 \row \li \c padding-top
1154 \li <length>px
1155 \li Top table cell padding in pixels
1156 \row \li \c padding-bottom
1157 \li <length>px
1158 \li Bottom table cell padding in pixels
1159 \row \li \c padding-left
1160 \li <length>px
1161 \li Left table cell padding in pixels
1162 \row \li \c padding-right
1163 \li <length>px
1164 \li Right table cell padding in pixels
1165 \row \li \c padding
1166 \li <length>px
1167 \li Shorthand for setting all the padding properties at once.
1168 \row \li \c vertical-align
1169 \li baseline | sub | super | middle | top | bottom
1170 \li Vertical text alignment. For vertical alignment in text table cells only middle, top, and bottom apply.
1171 \row \li \c border-collapse
1172 \li collapse | separate
1173 \li Border Collapse mode for text tables. If set to collapse, cell-spacing will not be applied.
1174 \row \li \c border-color
1175 \li <color>
1176 \li Border color for text tables and table cells.
1177 \row \li \c border-top-color
1178 \li <color>
1179 \li Top border color for table cells.
1180 \row \li \c border-bottom-color
1181 \li <color>
1182 \li Bottom border color for table cells.
1183 \row \li \c border-left-color
1184 \li <color>
1185 \li Left border color for table cells.
1186 \row \li \c border-right-color
1187 \li <color>
1188 \li Right border color for table cells.
1189 \row \li \c border-style
1190 \li none | dotted | dashed | dot-dash | dot-dot-dash | solid | double | groove | ridge | inset | outset
1191 \li Border style for text tables and table cells.
1192 \row \li \c border-top-style
1193 \li <border-style>
1194 \li Top border style for table cells.
1195 \row \li \c border-bottom-style
1196 \li <border-style>
1197 \li Bottom border style for table cells.
1198 \row \li \c border-left-style
1199 \li <border-style>
1200 \li Left border style for table cells.
1201 \row \li \c border-right-style
1202 \li <border-style>
1203 \li Right border style for table cells.
1204 \row \li \c border-width
1205 \li <width>px
1206 \li Width of table or cell border
1207 \row \li \c border-top-width
1208 \li <length>px
1209 \li Top border width for table cells.
1210 \row \li \c border-bottom-width
1211 \li <length>px
1212 \li Bottom border width for table cells.
1213 \row \li \c border-left-width
1214 \li <length>px
1215 \li Left border width for table cells.
1216 \row \li \c border-right-width
1217 \li <length>px
1218 \li Right border width for table cells.
1219 \row \li \c border-top
1220 \li <width>px <border-style> <border-color>
1221 \li Shorthand for setting top border width, style and color
1222 \row \li \c border-bottom
1223 \li <width>px <border-style> <border-color>
1224 \li Shorthand for setting bottom border width, style and color
1225 \row \li \c border-left
1226 \li <width>px <border-style> <border-color>
1227 \li Shorthand for setting left border width, style and color
1228 \row \li \c border-right
1229 \li <width>px <border-style> <border-color>
1230 \li Shorthand for setting right border width, style and color
1231 \row \li \c border-top
1232 \li <width>px <border-style> <border-color>
1233 \li Shorthand for setting top border width, style and color
1234 \row \li \c border-bottom
1235 \li <width>px <border-style> <border-color>
1236 \li Shorthand for setting bottom border width, style and color
1237 \row \li \c border
1238 \li <width>px <border-style> <border-color>
1239 \li Shorthand for setting all four border's width, style and color
1240 \row \li \c background
1241 \li [ <'background-color'> || <'background-image'> ]
1242 \li Background shorthand property
1243 \row \li \c page-break-before
1244 \li [ auto | always ]
1245 \li Make it possible to enforce a page break before the paragraph/table
1246 \row \li \c page-break-after
1247 \li [ auto | always ]
1248 \li Make it possible to enforce a page break after the paragraph/table
1249 \row \li \c float
1250 \li [ left | right | none ]
1251 \li Specifies where an image or a text will be placed in another element. Note that the \c float property is
1252 only supported for tables and images.
1253 \row \li \c text-transform
1254 \li [ uppercase | lowercase ]
1255 \li Select the transformation that will be performed on the text prior to displaying it.
1256 \row \li \c font-kerning
1257 \li [ normal | none ]
1258 \li Enables or disables kerning between text characters.
1259 \row \li \c font-variant
1260 \li small-caps
1261 \li Perform the smallcaps transformation on the text prior to displaying it.
1262 \row \li \c word-spacing
1263 \li <width>px
1264 \li Specifies an alternate spacing between each word.
1265 \row \li \c line-height
1266 \li <number>[% | px | pt | cm]
1267 \li Specifies the height of a line. It can be one of the
1268 following:
1269 \list
1270 \li fixed line height in pixels, points, or centimeters.
1271 \li a percentage of the current font size.
1272 \endlist
1273 \endtable
1274
1275 \note Certain CSS properties are only supported when applied to a block tag, such as \c{<p>}.
1276 Setting these properties on a \c{<span>}, for instance, will have no effect. The margin is one
1277 example of such a property. See QTextBlockFormat and QTextCharFormat for an overview of the
1278 formatting options available on blocks and spans in QTextDocument.
1279
1280 \section1 Qt-specific CSS properties
1281
1282 Besides the standard CSS properties listed earlier, the following
1283 Qt-specific properties can also be used to style a text block:
1284
1285 \table
1286 \header \li Property
1287 \li Values
1288 \li Description
1289 \row
1290 \li \c -qt-block-indent
1291 \li \c <number>
1292 \li Indents the text block by the specified no. spaces.
1293 \row
1294 \li \c -qt-list-indent
1295 \li \c <number>
1296 \li Indents the list items by the specified no. of spaces.
1297 \row
1298 \li \c -qt-list-number-prefix
1299 \li \c <string>
1300 \li Prefixes the given string to list number in an HTML ordered list.
1301 \row
1302 \li \c -qt-list-number-suffix
1303 \li <string>
1304 \li Suffixes the given string to list number in an HTML ordered list.
1305 \row
1306 \li \c -qt-paragraph-type
1307 \li \c empty
1308 \li Hides the text block.
1309 \row
1310 \li \c -qt-table-type
1311 \li \c{root | frame}
1312 \li \c root renders the text blocks inline without borders and
1313 indentation, whereas \c frame renders them on a new line
1314 with a frame around.
1315 \row
1316 \li \c -qt-user-state
1317 \li \c <number>
1318 \li Adds it as user data for the text block.
1319 \endtable
1320
1321 \section1 Supported CSS Selectors
1322
1323 All CSS 2.1 selector classes are supported except pseudo-class selectors such
1324 as \c{:first-child}, \c{:visited} and \c{:hover}.
1325
1326*/