diff options
Diffstat (limited to 'doc/src/richtext.qdoc')
| -rw-r--r-- | doc/src/richtext.qdoc | 1076 |
1 files changed, 0 insertions, 1076 deletions
diff --git a/doc/src/richtext.qdoc b/doc/src/richtext.qdoc deleted file mode 100644 index 405afd1..0000000 --- a/doc/src/richtext.qdoc +++ /dev/null @@ -1,1076 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page richtext.html -\nextpage Rich Text Document Structure - -\title Rich Text Processing -\ingroup architecture -\ingroup text-processing -\brief An overview of Qt's rich text processing, editing and display features. - -The Scribe framework provides a set of classes for reading and manipulating -structured rich text documents. Unlike previous rich text support in Qt, the -new classes are centered around the QTextDocument class rather than raw -textual information. This enables the developer to create and modify -structured rich text documents without having to prepare content in an -intermediate markup format. - -The information within a document can be accessed via two complementary -interfaces: A cursor-based interface is used for editing, and a read-only -hierarchical interface provides a high level overview of the document -structure. The main advantage of the cursor-based interface is that the -text can be edited using operations that mimic a user's interaction with -an editor, without losing the underlying structure of the document. The -read-only hierarchical interface is most useful when performing operations -such as searching and document export. - -This document is divided up into chapters for convenient reference: - -\list -\i \l{Rich Text Document Structure} outlines - the different kinds of elements in a QTextDocument, and describes how - they are arranged in a document structure. -\i \l{The QTextCursor Interface} explains how rich - text documents can be edited using the cursor-based interface. -\i \l{Common Rich Text Editing Tasks} examines some - common tasks that involve reading or manipulating rich text documents. -\i \l{Advanced Rich Text Processing} examines advanced rich text editing tasks. -\i \l{Supported HTML Subset} lists the HTML tags supported by QTextDocument. -\endlist - -See also the list of \l{Text Processing Classes}. - -*/ - -/*! -\page richtext-structure.html -\contentspage richtext.html Contents -\previouspage Rich Text Processing -\nextpage The QTextCursor Interface - -\title Rich Text Document Structure - -\tableofcontents - -The structured representation of a text document presents its contents as -a hierarchy of text blocks, frames, tables, and other objects. These provide -a logical structure to the document and describe how their contents will be -displayed. Generally, frames and tables are used to group other -structures while text blocks contain the actual textual information. - -New elements are created and inserted into the document programmatically -\l{richtext-cursor.html}{with a QTextCursor} or by using an editor -widget, such as QTextEdit. Elements can be given a particular format when -they are created; otherwise they take the cursor's current format for the -element. - -\table -\row -\i \inlineimage richtext-document.png -\i \bold{Basic structure} - -The "top level" of a document might be populated in the way shown. -Each document always contains a root frame, and this always contains -at least one text block. - -For documents with some textual content, the root -frame usually contains a sequence of blocks and other elements. - -Sequences of frames and tables are always separated by text blocks in a -document, even if the text blocks contain no information. This ensures that -new elements can always be inserted between existing structures. -\endtable - -In this chapter, we look at each of the structural elements -used in a rich text document, outline their features and uses, and show -how to examine their contents. Document editing is described in -\l{richtext-cursor.html}{The QTextCursor Interface}. - -\section1 Rich Text Documents - -QTextDocument objects contain all the information required to construct -rich text documents for use with a QTextEdit widget or in a custom editor. -Although QTextEdit makes it easy to display and edit rich text, documents -can also be used independently of any editor widget, for example: - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 0 - -Alternatively, they can be extracted from an existing editor: - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 1 - -This flexibility enables applications to handle multiple rich text -documents without the overhead of multiple editor widgets, or requiring -documents to be stored in some intermediate format. - -An empty document contains a root frame which itself contains a single -empty text block. The \l{richtext-cursor.html}{text cursor interface} -automatically inserts new document elements into the root frame, and -ensures that it is padded with empty blocks where necessary. - -We obtain the root frame in the following manner: - -\snippet doc/src/snippets/textdocument-frames/xmlwriter.h 0 -\snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 0 - -When navigating the document structure, it is useful to begin at the -root frame because it provides access to the entire document structure. - -\section1 Document Elements - -Rich text documents usually consist of common elements such as paragraphs, -frames, tables, and lists. These are represented in a QTextDocument -by the QTextBlock, QTextFrame, QTextTable, and QTextList classes. -Unlike the other elements in a document, images are represented by -specially formatted text fragments. This enables them to be placed -formatted inline with the surrounding text. - -The basic structural building blocks in documents are QTextBlock and -QTextFrame. Blocks themselves contain fragments of rich text -(QTextFragment), but these do not directly influence the high level -structure of a document. - -Elements which can group together other document elements are typically -subclasses of QTextObject, and fall into two categories: Elements that -group together text blocks are subclasses of QTextBlockGroup, and those -that group together frames and other elements are subclasses of QTextFrame. - -\section2 Text Blocks - -Text blocks are provided by the QTextBlock class. - -Text blocks group together fragments of text with different character formats, -and are used to represent paragraphs in the document. Each block -typically contains a number of text fragments with different styles. -Fragments are created when text is inserted into the document, and more -of them are added when the document is edited. The document splits, merges, -and removes fragments to efficiently represent the different styles -of text in the block. - -The fragments within a given block can be examined by using a -QTextBlock::iterator to traverse the block's internal structure: - -\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 3 -\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 5 -\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 6 - -Blocks are also used to represent list items. As a result, blocks can -define their own character formats which contain information about -block-level decoration, such as the type of bullet points used for -list items. The formatting for the block itself is described by the -QTextBlockFormat class, and describes properties such as text alignment, -indentation, and background color. - -Although a given document may contain complex structures, once we have a -reference to a valid block in the document, we can navigate between each -of the text blocks in the order in which they were written: - -\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 0 -\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 1 -\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 2 - -This method is useful for when you want to extract just the rich text from a -document because it ignores frames, tables, and other types of structure. - -QTextBlock provides comparison operators that make it easier to manipulate -blocks: \l{QTextBlock::operator==()}{operator==()} and -\l{QTextBlock::operator!=()}{operator!=()} are used to test whether two -blocks are the same, and \l{QTextBlock::operator<()}{operator<()} is used -to determine which one occurs first in a document. - -\section2 Frames - -Frames are provided by the QTextFrame class. - -Text frames group together blocks of text and child frames, creating -document structures that are larger than paragraphs. The format of a frame -specifies how it is rendered and positioned on the page. Frames are -either inserted into the text flow, or they float on the left or right -hand side of the page. -Each document contains a root frame that contains all the other document -elements. As a result, all frames except the root frame have a parent -frame. - -Since text blocks are used to separate other document elements, each -frame will always contain at least one text block, and zero or more -child frames. We can inspect the contents of a frame by using a -QTextFrame::iterator to traverse the frame's child elements: - -\snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 1 -\snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 2 - -Note that the iterator selects both frames and blocks, so it is necessary -to check which it is referring to. This allows us to navigate the document -structure on a frame-by-frame basis yet still access text blocks if -required. Both the QTextBlock::iterator and QTextFrame::iterator classes -can be used in complementary ways to extract the required structure from -a document. - -\section2 Tables - -Tables are provided by the QTextTable class. - -Tables are collections of cells that are arranged in rows and columns. -Each table cell is a document element with its own character format, but it -can also contain other elements, such as frames and text blocks. Table cells -are automatically created when the table is constructed, or when extra rows -or columns are added. They can also be moved between tables. - -QTextTable is a subclass of QTextFrame, so tables are treated like frames -in the document structure. For each frame that we encounter in the -document, we can test whether it represents a table, and deal with it in a -different way: - -\snippet doc/src/snippets/textdocument-tables/xmlwriter.cpp 0 -\snippet doc/src/snippets/textdocument-tables/xmlwriter.cpp 1 - -The cells within an existing table can be examined by iterating through -the rows and columns. - -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 9 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 10 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 11 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 12 - - -\section2 Lists - -Lists are provided by the QTextList class. - -Lists are sequences of text blocks that are formatted in the usual way, but -which also provide the standard list decorations such as bullet points and -enumerated items. Lists can be nested, and will be indented if the list's -format specifies a non-zero indentation. - -We can refer to each list item by its index in the list: - -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 0 -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 1 -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 2 - -Since QTextList is a subclass of QTextBlockGroup, it does not group the -list items as child elements, but instead provides various functions for -managing them. This means that any text block we find when traversing a -document may actually be a list item. We can ensure that list items are -correctly identified by using the following code: - -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 3 -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 4 -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 5 -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 6 -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 7 - - -\section2 Images - -Images in QTextDocument are represented by text fragments that reference -external images via the resource mechanism. Images are created using the -cursor interface, and can be modified later by changing the character -format of the image's text fragment: - -\snippet doc/src/snippets/textdocument-imageformat/main.cpp 0 -\snippet doc/src/snippets/textdocument-imageformat/main.cpp 1 -\snippet doc/src/snippets/textdocument-imageformat/main.cpp 2 - -The fragment that represents the image can be found by iterating over -the fragments in the text block that contains the image. -*/ - -/*! -\page richtext-cursor.html -\contentspage richtext.html Contents -\previouspage Rich Text Document Structure -\nextpage Common Rich Text Editing Tasks - -\title The QTextCursor Interface - -\tableofcontents - -The QTextCursor interface allows documents and their structure to be -edited in a way that should be familiar to most users of text editors and -document editing software. Rich text documents can have multiple cursors -associated with them, and each of these contains information about their -position in the document and any selections that they may hold. This -cursor-based paradigm makes common operations, such as cutting and pasting -text, simple to implement programmatically, yet it also allows more complex -editing operations to be performed on the document. - -This chapter describes most of the common editing operations that you -will need to perform using a cursor, from basic insertion of text and -document elements to more complex manipulation of document structures. - -\section1 Cursor-Based Editing - -At the simplest level, text documents are made up of a string of characters, -marked up in some way to represent the block structure of the text within the -document. QTextCursor provides a cursor-based interface that allows the -contents of a QTextDocument to be manipulated at the character level. Since -the elements (blocks, frames, tables, etc.) are also encoded in the character -stream, the document structure can itself be changed by the cursor. - -The cursor keeps track of its location within its parent document, and can -report information about the surrounding structure, such as the enclosing -text block, frame, table, or list. The formats of the enclosing structures -can also be directly obtained through the cursor. - -\section2 Using a Cursor - -The main use of a cursor is to insert or modify text within a block. -We can use a text editor's cursor to do this: - -\snippet doc/src/snippets/textblock-formats/main.cpp 0 - -Alternatively, we can obtain a cursor directly from a document: - -\snippet doc/src/snippets/textdocument-images/main.cpp 0 - -The cursor is positioned at the start of the document so that we can write -into the first (empty) block in the document. - -\section2 Grouping Cursor Operations - -A series of editing operations can be packaged together so that they can -be replayed, or undone together in a single action. This is achieved by -using the \c beginEditBlock() and \c endEditBlock() functions in the -following way, as in the following example where we select the word that -contains the cursor: - -\snippet doc/src/snippets/textdocument-selections/mainwindow.cpp 0 - -If editing operations are not grouped, the document automatically records -the individual operations so that they can be undone later. Grouping -operations into larger packages can make editing more efficient both for -the user and for the application, but care has to be taken not to group too -many operations together as the user may want find-grained control over the -undo process. - -\section2 Multiple Cursors - -Multiple cursors can be used to simultaneously edit the same document, -although only one will be visible to the user in a QTextEdit widget. -The QTextDocument ensures that each cursor writes text correctly and -does not interfere with any of the others. - -\omit -\snippet doc/src/snippets/textdocument-cursors/main.cpp 0 -\snippet doc/src/snippets/textdocument-cursors/main.cpp 1 -\endomit - -\section1 Inserting Document Elements - -QTextCursor provides several functions that can be used to change the -structure of a rich text document. Generally, these functions allow -document elements to be created with relevant formatting information, -and they are inserted into the document at the cursor's position. - -The first group of functions insert block-level elements, and update the -cursor position, but they do not return the element that was inserted: - -\list -\i \l{QTextCursor::insertBlock()}{insertBlock()} inserts a new text block - (paragraph) into a document at the cursor's position, and moves the - cursor to the start of the new block. -\i \l{QTextCursor::insertFragment()}{insertFragment()} inserts an existing - text fragment into a document at the cursor's position. -\i \l{QTextCursor::insertImage()}{insertImage()} inserts an image into a - document at the cursor's position. -\i \l{QTextCursor::insertText()}{insertText()} inserts text into the - document at the cursor's position. -\endlist - -You can examine the contents of the element that was inserted through the -cursor interface. - -The second group of functions insert elements that provide structure to -the document, and return the structure that was inserted: - -\list -\i \l{QTextCursor::insertFrame()}{insertFrame()} inserts a frame into the - document \e after the cursor's current block, and moves the cursor to - the start of the empty block in the new frame. -\i \l{QTextCursor::insertList()}{insertList()} inserts a list into the - document at the cursor's position, and moves the cursor to the start - of the first item in the list. -\i \l{QTextCursor::insertTable()}{insertTable()} inserts a table into - the document \e after the cursor's current block, and moves the cursor - to the start of the block following the table. -\endlist - -These elements either contain or group together other elements in the -document. - -\section2 Text and Text Fragments - -Text can be inserted into the current block in the current character -format, or in a custom format that is specified with the text: - -\snippet doc/src/snippets/textdocument-charformats/main.cpp 0 - -Once the character format has been used with a cursor, that format becomes -the default format for any text inserted with that cursor until another -character format is specified. - -If a cursor is used to insert text without specifying a character format, -the text will be given the character format used at that position in the -document. - -\section2 Blocks - -Text blocks are inserted into the document with the -\l{QTextCursor::insertBlock()}{insertBlock()} function. - -\snippet doc/src/snippets/textblock-formats/main.cpp 1 - -The cursor is positioned at the start of the new block. - -\section2 Frames - -Frames are inserted into a document using the cursor, and will be placed -within the cursor's current frame \e after the current block. -The following code shows how a frame can be inserted between two text -blocks in a document's root frame. We begin by finding the cursor's -current frame: - -\snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 0 - -We insert some text in this frame then set up a frame format for the -child frame: - -\snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 1 - -The frame format will give the frame an external margin of 32 pixels, -internal padding of 8 pixels, and a border that is 4 pixels wide. -See the QTextFrameFormat documentation for more information about -frame formats. - -The frame is inserted into the document after the preceding text: - -\snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 2 - -We add some text to the document immediately after we insert the frame. -Since the text cursor is positioned \e{inside the frame} when it is inserted -into the document, this text will also be inserted inside the frame. - -Finally, we position the cursor outside the frame by taking the last -available cursor position inside the frame we recorded earlier: - -\snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 3 - -The text that we add last is inserted after the child frame in the -document. Since each frame is padded with text blocks, this ensures that -more elements can always be inserted with a cursor. - -\section2 Tables - -Tables are inserted into the document using the cursor, and will be -placed within the cursor's current frame \e after the current block: - -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 0 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 3 - -Tables can be created with a specific format that defines the overall -properties of the table, such as its alignment, background color, and -the cell spacing used. It can also determine the constraints on each -column, allowing each of them to have a fixed width, or resize according -to the available space. - -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 2 - -The columns in the table created above will each take up a certain -percentage of the available width. Note that the table format is -optional; if you insert a table without a format, some sensible -default values will be used for the table's properties. - -Since cells can contain other document elements, they too can be -formatted and styled as necessary. - -Text can be added to the table by navigating to each cell with the cursor -and inserting text. - -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 4 - -We can create a simple timetable by following this approach: - -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 5 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 6 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 7 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 8 - -\section2 Lists - -Lists of block elements can be automatically created and inserted into the -document at the current cursor position. Each list that is created in this -way requires a list format to be specified: - -\snippet doc/src/snippets/textdocument-lists/mainwindow.cpp 0 - -The above code first checks whether the cursor is within an existing list -and, if so, gives the list format for the new list a suitable level of -indentation. This allows nested lists to be created with increasing -levels of indentation. A more sophisticated implementation would also use -different kinds of symbol for the bullet points in each level of the list. - -\section2 Images - -Inline images are added to documents through the cursor in the usual manner. -Unlike many other elements, all of the image properties are specified by the -image's format. This means that a QTextImageFormat object has to be -created before an image can be inserted: - -\snippet doc/src/snippets/textdocument-images/main.cpp 1 - -The image name refers to an entry in the application's resource file. -The method used to derive this name is described in -\l{resources.html}{The Qt Resource System}. - -*/ - -/*! -\page richtext-common-tasks.html -\contentspage richtext.html Contents -\previouspage The QTextCursor Interface -\nextpage Advanced Rich Text Processing - -\title Common Rich Text Editing Tasks - -\tableofcontents - -There are a number of tasks that are often performed by developers -when editing and processing text documents using Qt. These include the use -of display widgets such as QTextBrowser and QTextEdit, creation of -documents with QTextDocument, editing using a QTextCursor, and -exporting the document structure. -This document outlines some of the more common ways of using the rich -text classes to perform these tasks, showing convenient patterns that can -be reused in your own applications. - -\section1 Using QTextEdit - -A text editor widget can be constructed and used to display HTML in the -following way: - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 2 - -By default, the text editor contains a document with a root frame, inside -which is an empty text block. This document can be obtained so that it can -be modified directly by the application: - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 3 - -The text editor's cursor may also be used to edit a document: - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 4 - -Although a document can be edited using many cursors at once, a QTextEdit -only displays a single cursor at a time. Therefore, if we want to update the -editor to display a particular cursor or its selection, we need to set the -editor's cursor after we have modified the document: - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 5 - -\section1 Selecting Text - -Text is selected by moving the cursor using operations that are similar to -those performed by a user in a text editor. To select text between two -points in the document, we need to position the cursor at the first point -then move it using a special mode (\l{QTextCursor::MoveMode}) with a -move operation (\l{QTextCursor::MoveOperation}). -When we select the text, we leave the selection anchor at the old cursor -position just as the user might do by holding down the Shift key when -selecting text: - -\snippet doc/src/snippets/textdocument-selections/mainwindow.cpp 1 - -In the above code, a whole word is selected using this method. QTextCursor -provides a number of common move operations for selecting individual -characters, words, lines, and whole blocks. - -\section1 Finding Text - -QTextDocument provides a cursor-based interface for searching, making -it easy to find and modify text in the style of a text editor. The following -code finds all the instances of a particular word in a document, and changes -the color of each: - -\snippet doc/src/snippets/textdocument-find/main.cpp 0 -\snippet doc/src/snippets/textdocument-find/main.cpp 1 - -Note that the cursor does not have to be moved after each search and replace -operation; it is always positioned at the end of the word that was just -replaced. - -\section1 Printing Documents - -QTextEdit is designed for the display of large rich text documents that are -read on screen, rendering them in the same way as a web browser. As a result, -it does not automatically break the contents of the document into page-sized -pieces that are suitable for printing. - -QTextDocument provides a \l{QTextDocument::print()}{print()} function to -allow documents to be printed using the QPrinter class. The following code -shows how to prepare a document in a QTextEdit for printing with a QPrinter: - -\snippet doc/src/snippets/textdocument-printing/mainwindow.cpp 0 - -The document is obtained from the text editor, and a QPrinter is constructed -then configured using a QPrintDialog. If the user accepts the printer's -configuration then the document is formatted and printed using the -\l{QTextDocument::print()}{print()} function. - -*/ - -/*! -\page richtext-advanced-processing.html -\contentspage richtext.html Contents -\previouspage Common Rich Text Editing Tasks -\nextpage Supported HTML Subset - -\title Advanced Rich Text Processing - -\section1 Handling Large Files - -Qt does not limit the size of files that are used for text -processing. In most cases, this will not present a problem. For -especially large files, however, you might experience that your -application will become unresponsive or that you will run out of -memory. The size of the files you can load depends on your -hardware and on Qt's and your own application's implementation. - -If you are faced with this problem, we recommend that you address the -following issues: - -\list - \o You should consider breaking up large paragraphs into smaller - ones as Qt handles small paragraphs better. You could also - insert line breaks at regular intervals, which will look the - same as one large paragraph in a QTextEdit. - \o You can reduce the amount of blocks in a QTextDocument with - \l{QTextDocument::}{maximumBlockCount()}. The document is only - as large as the number of blocks as far as QTextEdit is concerned. - \o When adding text to a text edit, it is an advantage to add it - in an edit block (see example below). The result is that the - text edit does not need to build the entire document structure at once. -\endlist - -We give an example of the latter technique from the list. We assume that -the text edit is visible. - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 6 - -\omit -Ideas for other sections: - - * Hiding QTextBlock elements. - * Changing the word wrapping mode in QTextEdit. Custom word wrapping? -\endomit -*/ - -/*! - \page richtext-html-subset.html - \title Supported HTML Subset - \brief Describes the support for HTML markup in text widgets. - - \contentspage richtext.html Contents - \previouspage Common Rich Text Editing Tasks - - Qt's text widgets are able to display rich text, specified using a subset of \l{HTML 4} - markup. Widgets that use QTextDocument, such as QLabel and QTextEdit, are able to display - rich text specified in this way. - - \tableofcontents - - \section1 Using HTML Markup in Text Widgets - - Widgets automatically detect HTML markup and display rich text accordingly. For example, - setting a label's \l{QLabel::}{text} property with the string \c{"<b>Hello</b> <i>Qt!</i>"} - will result in the label displaying text like this: \bold{Hello} \e{Qt!} - - When HTML markup is used for text, Qt follows the rules defined by the \l{HTML 4} - specification. This includes default properties for text layout, such as the - direction of the text flow (left-to-right) which can be changed by applying the - \l{#Block Attributes}{\c dir} attribute to blocks of text. - - \section1 Supported Tags - - The following table lists the HTML tags supported by Qt's - \l{Rich Text Processing}{rich text} engine: - - \table - \header \o Tag - \o Description - \o Comment - \row \o \c a - \o Anchor or link - \o Supports the \c href and \c name attributes. - \row \o \c address - \o Address - \o - \row \o \c b - \o Bold - \o - \row \o \c big - \o Larger font - \o - \row \o \c blockquote - \o Indented paragraph - \o - \row \o \c body - \o Document body - \o Supports the \c bgcolor attribute, which - can be a Qt \l{QColor::setNamedColor()}{color name} - or a \c #RRGGBB color specification. - \row \o \c br - \o Line break - \o - \row \o \c center - \o Centered paragraph - \o - \row \o \c cite - \o Inline citation - \o Same as \c i. - \row \o \c code - \o Code - \o Same as \c tt. - \row \o \c dd - \o Definition data - \o - \row \o \c dfn - \o Definition - \o Same as \c i. - \row \o \c div - \o Document division - \o Supports the standard \l{block attributes}. - \row \o \c dl - \o Definition list - \o Supports the standard \l{block attributes}. - \row \o \c dt - \o Definition term - \o Supports the standard \l{block attributes}. - \row \o \c em - \o Emphasized - \o Same as \c i. - \row \o \c font - \o Font size, family, and/or color - \o Supports the following attributes: - \c size, \c face, and \c color (Qt - \l{QColor::setNamedColor()}{color names} or - \c #RRGGBB). - \row \o \c h1 - \o Level 1 heading - \o Supports the standard \l{block attributes}. - \row \o \c h2 - \o Level 2 heading - \o Supports the standard \l{block attributes}. - \row \o \c h3 - \o Level 3 heading - \o Supports the standard \l{block attributes}. - \row \o \c h4 - \o Level 4 heading - \o Supports the standard \l{block attributes}. - \row \o \c h5 - \o Level 5 heading - \o Supports the standard \l{block attributes}. - \row \o \c h6 - \o Level 6 heading - \o Supports the standard \l{block attributes}. - \row \o \c head - \o Document header - \o - \row \o \c hr - \o Horizontal line - \o Supports the \c width attribute, which can - be specified as an absolute or relative (\c %) value. - \row \o \c html - \o HTML document - \o - \row \o \c i - \o Italic - \o - \row \o \c img - \o Image - \o Supports the \c src, \c source - (for Qt 3 compatibility), \c width, and \c height - attributes. - \row \o \c kbd - \o User-entered text - \o - \row \o \c meta - \o Meta-information - \o If a text encoding is specified using the \c{meta} tag, - it is picked up by Qt::codecForHtml(). - Likewise, if an encoding is specified to - QTextDocument::toHtml(), the encoding is stored using - a \c meta tag, for example: - - \snippet doc/src/snippets/code/doc_src_richtext.qdoc 7 - - \row \o \c li - \o List item - \o - \row \o \c nobr - \o Non-breakable text - \o - \row \o \c ol - \o Ordered list - \o Supports the standard \l{list attributes}. - \row \o \c p - \o Paragraph - \o Left-aligned by default. Supports the standard - \l{block attributes}. - \row \o \c pre - \o Preformated text - \o - \row \o \c qt - \o Qt rich-text document - \o Synonym for \c html. Provided for compatibility with - earlier versions of Qt. - \row \o \c s - \o Strikethrough - \o - \row \o \c samp - \o Sample code - \o Same as \c tt. - \row \o \c small - \o Small font - \o - \row \o \c span - \o Grouped elements - \o - \row \o \c strong - \o Strong - \o Same as \c b. - \row \o \c sub - \o Subscript - \o - \row \o \c sup - \o Superscript - \o - \row \o \c table - \o Table - \o Supports the following attributes: \c border, - \c bgcolor (Qt \l{QColor::setNamedColor()}{color names} - or \c #RRGGBB), \c cellspacing, \c cellpadding, - \c width (absolute or relative), and \c height. - \row \o \c tbody - \o Table body - \o Does nothing. - \row \o \c td - \o Table data cell - \o Supports the standard \l{table cell attributes}. - \row \o \c tfoot - \o Table footer - \o Does nothing. - \row \o \c th - \o Table header cell - \o Supports the standard \l{table cell attributes}. - \row \o \c thead - \o Table header - \o If the \c thead tag is specified, it is used when printing tables - that span multiple pages. - \row \o \c title - \o Document title - \o The value specified using the \c - title tag is available through - QTextDocument::metaInformation(). - \row \o \c tr - \o Table row - \o Supports the \c bgcolor attribute, which - can be a Qt \l{QColor::setNamedColor()}{color name} - or a \c #RRGGBB color specification. - \row \o \c tt - \o Typewrite font - \o - \row \o \c u - \o Underlined - \o - \row \o \c ul - \o Unordered list - \o Supports the standard \l{list attributes}. - \row \o \c var - \o Variable - \o Same as \c i. - \endtable - - \section1 Block Attributes - - The following attributes are supported by the \c div, \c dl, \c - dt, \c h1, \c h2, \c h3, \c h4, \c h5, \c h6, \c p tags: - - \list - \o \c align (\c left, \c right, \c center, \c justify) - \o \c dir (\c ltr, \c rtl) - \endlist - - \section1 List Attributes - - The following attribute is supported by the \c ol and \c ul tags: - - \list - \o \c type (\c 1, \c a, \c A, \c square, \c disc, \c circle) - \endlist - - \section1 Table Cell Attributes - - The following attributes are supported by the \c td and \c th - tags: - - \list - \o \c width (absolute, relative, or no-value) - \o \c bgcolor (Qt \l{QColor::setNamedColor()}{color names} or \c #RRGGBB) - \o \c colspan - \o \c rowspan - \o \c align (\c left, \c right, \c center, \c justify) - \o \c valign (\c top, \c middle, \c bottom) - \endlist - - \section1 CSS Properties - The following table lists the CSS properties supported by Qt's - \l{Rich Text Processing}{rich text} engine: - - \table - \header \o Property - \o Values - \o Description - \row - \o \c background-color - \o <color> - \o Background color for elements - \row - \o \c background-image - \o <uri> - \o Background image for elements - \row \o \c color - \o <color> - \o Text foreground color - \row \o \c font-family - \o <family name> - \o Font family name - \row \o \c font-size - \o [ small | medium | large | x-large | xx-large ] | <size>pt | <size>px - \o Font size relative to the document font, or specified in points or pixels - \row \o \c font-style - \o [ normal | italic | oblique ] - \o - \row \o \c font-weight - \o [ normal | bold | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 ] - \o Specifies the font weight used for text, where \c normal and \c bold - are mapped to the corresponding QFont weights. Numeric values are - 8 times the equivalent QFont weight values. - \row \o \c text-decoration - \o none | [ underline || overline || line-through ] - \o Additional text effects - \row \o \c font - \o [ [ <'font-style'> || <'font-weight'> ]? <'font-size'> <'font-family'> ] - \o Font shorthand property - \row \o \c text-indent - \o <length>px - \o First line text indentation in pixels - \row \o \c white-space - \o normal | pre | nowrap | pre-wrap - \o Declares how whitespace in HTML is handled. - \row \o \c margin-top - \o <length>px - \o Top paragraph margin in pixels - \row \o \c margin-bottom - \o <length>px - \o Bottom paragraph margin in pixels - \row \o \c margin-left - \o <length>px - \o Left paragraph margin in pixels - \row \o \c margin-right - \o <length>px - \o Right paragraph margin in pixels - \row \o \c padding-top - \o <length>px - \o Top table cell padding in pixels - \row \o \c padding-bottom - \o <length>px - \o Bottom table cell padding in pixels - \row \o \c padding-left - \o <length>px - \o Left table cell padding in pixels - \row \o \c padding-right - \o <length>px - \o Right table cell padding in pixels - \row \o \c padding - \o <length>px - \o Shorthand for setting all the padding properties at once. - \row \o \c vertical-align - \o baseline | sub | super | middle | top | bottom - \o Vertical text alignment. For vertical alignment in text table cells only middle, top, and bottom apply. - \row \o \c border-color - \o <color> - \o Border color for text tables. - \row \o \c border-style - \o none | dotted | dashed | dot-dash | dot-dot-dash | solid | double | groove | ridge | inset | outset - \o Border style for text tables. - \row \o \c background - \o [ <'background-color'> || <'background-image'> ] - \o Background shorthand property - \row \o \c page-break-before - \o [ auto | always ] - \o Make it possible to enforce a page break before the paragraph/table - \row \o \c page-break-after - \o [ auto | always ] - \o Make it possible to enforce a page break after the paragraph/table - \row \o float - \o [ left | right | none ] - \o Specifies where an image or a text will be placed in another element. Note that the \c float property is - only supported for tables and images. - \row \o \c text-transform - \o [ uppercase | lowercase ] - \o Select the transformation that will be performed on the text prior to displaying it. - \row \o \c font-variant - \o small-caps - \o Perform the smallcaps transformation on the text prior to displaying it. - \row \o \c word-spacing - \o <width>px - \o Specifies an alternate spacing between each word. - \endtable - - \section1 Supported CSS Selectors - - All CSS 2.1 selector classes are supported except pseudo-class selectors such - as \c{:first-child}, \c{:visited} and \c{:hover}. - -*/ |