QTextEdit Class Reference

The QTextEdit widget provides a powerful single-page rich text editor. More...

#include <qtextedit.h>

---

Detailed Description

The QTextEdit widget provides a powerful single-page rich text editor.

---

QTextEdit is an advanced WYSIWYG viewer/editor supporting rich text formatting using HTML-style tags. It is optimized to handle large documents and to respond quickly to user input. QTextEdit has three modes of operation: \table \header \i Mode \i Command \i Notes \row \i Plain Text Editor \i setTextFormat(PlainText) \i Set text with setText(); text() returns plain text. Text attributes (e.g. colors) can be set, but plain text is always returned.^1. \row \i Rich Text Editor \i setTextFormat(RichText) \i Set text with setText(); text() returns rich text. Rich text editing is fairly limited. You can't set margins or insert images for example (although you can read and correctly display files that have margins set and that include images). This mode is mostly useful for editing small amounts of rich text. ^2. \row \i Text Viewer^3. \i setReadOnly(TRUE) \i Set text with setText() or append() (which has no undo history so is faster and uses less memory); text() returns plain or rich text depending on the textFormat(). This mode can correctly display a large subset of HTML tags. \endtable ^1.<small>We do \e not recommend using QTextEdit to create syntax highlighting editors because the current API is insufficient for this purpose. We hope to release a more complete API that will support syntax highlighting in a later release.</small> ^2.<small>A more complete API that supports setting margins, images, etc., is planned for a later Qt release.</small> ^3.<small>Qt 3.1 will provide a Log Viewer mode which is optimised for the fast and memory efficient display of large amounts of read only text.</small> We recommend that you always call setTextFormat() to set the mode you want to use. If you use \c AutoText then setText() and append() will try to determine whether the text they are given is plain text or rich text. If you use \c RichText then setText() and append() will assume that the text they are given is rich text. insert() simply inserts the text it is given. QTextEdit works on paragraphs and characters. A paragraph is a formatted string which is word-wrapped to fit into the width of the widget. By default when reading plain text, two newlines signify a paragraph. A document consists of zero or more paragraphs, indexed from 0. Characters are indexed on a per-paragraph basis, also indexed from 0. The words in the paragraph are aligned in accordance with the paragraph's alignment(). Paragraphs are separated by hard line breaks. Each character within a paragraph has its own attributes, for example, font and color. The text edit documentation uses the following concepts: \list \i \e{current format} -- this is the format at the current cursor position, \e and it is the format of the selected text if any. \i \e{current paragraph} -- the paragraph which contains the cursor. \endlist QTextEdit can display images (using QMimeSourceFactory), lists and tables. If the text is too large to view within the text edit's viewport, scrollbars will appear. The text edit can load both plain text and HTML files (a subset of HTML 3.2 and 4). The rendering style and the set of valid tags are defined by a styleSheet(). Custom tags can be created and placed in a custom style sheet. Change the style sheet with \l{setStyleSheet()}; see QStyleSheet for details. The images identified by image tags are displayed if they can be interpreted using the text edit's \l{QMimeSourceFactory}; see setMimeSourceFactory(). If you want a text browser with more navigation use QTextBrowser. If you just need to display a small piece of rich text use QLabel or QSimpleRichText. If you create a new QTextEdit, and want to allow the user to edit rich text, call setTextFormat(Qt::RichText) to ensure that the text is treated as rich text. (Rich text uses HTML tags to set text formatting attributes. See QStyleSheet for information on the HTML tags that are supported.). If you don't call setTextFormat() explicitly the text edit will guess from the text itself whether it is rich text or plain text. This means that if the text looks like HTML or XML it will probably be interpreted as rich text, so you should call setTextFormat(Qt::PlainText) to preserve such text. Note that we do not intend to add a full-featured web browser widget to Qt (because that would easily double Qt's size and only a few applications would benefit from it). The rich text support in Qt is designed to provide a fast, portable and efficient way to add reasonable online help facilities to applications, and to provide a basis for rich text editors. @section Using QTextEdit as a Display Widget QTextEdit can display a large HTML subset, including tables and images. The text is set or replaced using setText() which deletes any existing text and replaces it with the text passed in the setText() call. If you call setText() with legacy HTML (with setTextFormat(RichText) in force), and then call text(), the text that is returned may have different markup, but will render the same. Text can be inserted with insert(), paste(), pasteSubType() and append(). Text that is appended does not go into the undo history; this makes append() faster and consumes less memory. Text can also be cut(). The entire text is deleted with clear() and the selected text is deleted with removeSelectedText(). Selected (marked) text can also be deleted with del() (which will delete the character to the right of the cursor if no text is selected). Loading and saving text is achieved using setText() and text(), for example: @code QFile file( fileName ); // Read the text from a file if ( file.open( IO_ReadOnly ) ) { QTextStream ts( &file ); textEdit->setText( ts.read() ); } \endcode @code QFile file( fileName ); // Write the text to a file if ( file.open( IO_WriteOnly ) ) { QTextStream ts( &file ); ts << textEdit->text(); textEdit->setModified( FALSE ); } \endcode By default the text edit wraps words at whitespace to fit within the text edit widget. The setWordWrap() function is used to specify the kind of word wrap you want, or \c NoWrap if you don't want any wrapping. Call setWordWrap() to set a fixed pixel width \c FixedPixelWidth, or character column (e.g. 80 column) \c FixedColumnWidth with the pixels or columns specified with setWrapColumnOrWidth(). If you use word wrap to the widget's width \c WidgetWidth, you can specify whether to break on whitespace or anywhere with setWrapPolicy(). The background color is set differently than other widgets, using setPaper(). You specify a brush style which could be a plain color or a complex pixmap. Hypertext links are automatically underlined; this can be changed with setLinkUnderline(). The tab stop width is set with setTabStopWidth(). The zoomIn() and zoomOut() functions can be used to resize the text by increasing (decreasing for zoomOut()) the point size used. Images are not affected by the zoom functions. The lines() function returns the number of lines in the text and paragraphs() returns the number of paragraphs. The number of lines within a particular paragraph is returned by linesOfParagraph(). The length of the entire text in characters is returned by length(). You can scroll to an anchor in the text, e.g. \c{<a name="anchor">} with scrollToAnchor(). The find() function can be used to find and select a given string within the text. A read-only QTextEdit provides the same functionality as the (obsolete) QTextView. (QTextView is still supplied for compatibilityThe documentation for this class was generated from the following file:

• noncore/apps/opie-write/qtextedit.cpp

---