Q3TextEdit Class Reference
[Qt3Support module]

Introduction and Concepts

Q3TextEdit 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.

Q3TextEdit has four modes of operation:

Q3TextEdit can be used as a syntax highlighting editor when used in conjunction with QSyntaxHighlighter.

We recommend that you always call setTextFormat() to set the mode you want to use. If you use Qt::AutoText then setText() and append() will try to determine whether the text they are given is plain text or rich text. If you use Qt::RichText then setText() and append() will assume that the text they are given is rich text. insert() simply inserts the text it is given.

Q3TextEdit 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, one newline 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:

• current format -- this is the format at the current cursor position, and it is the format of the selected text if any.
• current paragraph -- the paragraph which contains the cursor.

Q3TextEdit can display images (using Q3MimeSourceFactory), lists and tables. If the text is too large to view within the text edit's viewport, scroll bars 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 setStyleSheet(); see Q3StyleSheet for details. The images identified by image tags are displayed if they can be interpreted using the text edit's Q3MimeSourceFactory; 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 Q3TextEdit, 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 Q3StyleSheet 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.

 QFile file(fileName); // Read the text from a file
 if (file.open(IO_ReadOnly)) {
     QTextStream stream(&file);
     textEdit->setText(stream.read());
 }

 QFile file(fileName); // Write the text to a file
 if (file.open(IO_WriteOnly)) {
     QTextStream stream(&file);
     stream << textEdit->text();
     textEdit->setModified(false);
 }

 This is <font color=red>red</font> while <b>this</b> is <font color=blue>blue</font>.
 <font color=green><font color=yellow>Yellow,</font> and <u>green</u>.

 Q3TextEdit * log = new Q3TextEdit(this);
 log->setTextFormat(Qt::LogText);
 Q3StyleSheetItem * item = new Q3StyleSheetItem(log->styleSheet(), "mytag");
 item->setColor("red");
 item->setFontWeight(QFont::Bold);
 item->setFontUnderline(true);
 log->append("This is a <mytag>custom tag</mytag>!");