Home · Overviews · Examples 

QTextEdit Class Reference
[com.trolltech.qt.gui module]

The QTextEdit class provides a widget that is used to edit and display both plain and rich text. More...

Inherits QAbstractScrollArea.

Inherited by QTextBrowser.


Detailed Description

The QTextEdit class provides a widget that is used to edit and display both plain and rich text.

Introduction and Concepts

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 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 signifies a paragraph. A document consists of zero or more paragraphs. 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.

QTextEdit can display images, 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).

If you just need to display a small piece of rich text use QLabel.

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.

The shape of the mouse cursor on a QTextEdit is Qt::IBeamCursor by default. It can be changed through the viewport's cursor property.

Using QTextEdit as a Display Widget

QTextEdit can display a large HTML subset, including tables and images.

The text is set or replaced using setHtml which deletes any existing text and replaces it with the text passed in the setHtml call. If you call setHtml with legacy HTML, and then call toHtml, the text that is returned may have different markup, but will render the same. The entire text can be deleted with clear.

Text itself can be inserted using the QTextCursor class or using the convenience functions insertHtml, insertPlainText, append or paste. QTextCursor is also able to insert complex objects like tables or lists into the document, and it deals with creating selections and applying changes to selected text.

By default the text edit wraps words at whitespace to fit within the text edit widget. The setLineWrapMode function is used to specify the kind of line wrap you want, or NoWrap if you don't want any wrapping. Call setLineWrapMode to set a fixed pixel width FixedPixelWidth, or character column (e.g. 80 column) FixedColumnWidth with the pixels or columns specified with setLineWrapColumnOrWidth. If you use word wrap to the widget's width WidgetWidth, you can specify whether to break on whitespace or anywhere with setWordWrapMode.

The find function can be used to find and select a given string within the text.

If you want to limit the total number of paragraphs in a QTextEdit, as it is for example open useful in a log viewer, then you can use QTextDocument's maximumBlockCount property for that.

Read-only Key Bindings

When QTextEdit is used read-only the key bindings are limited to navigation, and text may only be selected with the mouse:

KeypressesAction
Qt::UpArrowMoves one line up.
Qt::DownArrowMoves one line down.
Qt::LeftArrowMoves one character to the left.
Qt::RightArrowMoves one character to the right.
PageUpMoves one (viewport) page up.
PageDownMoves one (viewport) page down.
HomeMoves to the beginning of the text.
EndMoves to the end of the text.
Alt+WheelScrolls the page horizontally (the Wheel is the mouse wheel).
Ctrl+WheelZooms the text.
Ctrl+ASelects all text.

The text edit may be able to provide some meta-information. For example, the documentTitle function will return the text from within HTML <title> tags.

Using QTextEdit as an Editor

All the information about using QTextEdit as a display widget also applies here.

The current char format's attributes are set with setFontItalic, setFontWeight, setFontUnderline, setFontFamily, setFontPointSize, setTextColor and setCurrentFont. The current paragraph's alignment is set with setAlignment.

Selection of text is handled by the QTextCursor class, which provides functionality for creating selections, retrieving the text contents or deleting selections. You can retrieve the object that corresponds with the user-visible cursor using the textCursor method. If you want to set a selection in QTextEdit just create one on a QTextCursor object and then make that cursor the visible cursor using setCursor. The selection can be copied to the clipboard with copy, or cut to the clipboard with cut. The entire text can be selected using selectAll.

When the cursor is moved and the underlying formatting attributes change, the currentCharFormatChanged signal is emitted to reflect the new attributes at the new cursor position.

QTextEdit holds a QTextDocument object which can be retrieved using the document method. You can also set your own document object using setDocument. QTextDocument emits a textChanged signal if the text changes and it also provides a isModified() function which will return true if the text has been modified since it was either loaded or since the last call to setModified with false as argument. In addition it provides methods for undo and redo.

Drag and Drop

QTextEdit also supports custom drag and drop behavior. By default, QTextEdit will insert plain text, HTML and rich text when the user drops data of these MIME types onto a document. Reimplement canInsertFromMimeData and insertFromMimeData to add support for additional MIME types.

For example, to allow the user to drag and drop an image onto a QTextEdit, you could the implement these functions in the following way:

    bool TextEdit::canInsertFromMimeData( const QMimeData *source ) const
    {
        if (source->hasImage())
            return true;
        else
            return QTextEdit::canInsertFromMimeData(source);
    }

We add support for image MIME types by returning true. For all other MIME types, we use the default implementation.

    void TextEdit::insertFromMimeData( const QMimeData *source )
    {
        if (source->hasImage())
        {
            QImage image = qvariant_cast<QImage>(source->imageData());
            QTextCursor cursor = this->textCursor();
            QTextDocument *document = this->document();
            document->addResource(QTextDocument::ImageResource, QUrl("image"), image);
            cursor.insertImage("image");
        }
    }

We unpack the image from the QVariant held by the MIME source and insert it into the document as a resource.

Editing Key Bindings

The list of key bindings which are implemented for editing:

KeypressesAction
BackspaceDeletes the character to the left of the cursor.
DeleteDeletes the character to the right of the cursor.
Ctrl+CCopy the selected text to the clipboard.
Ctrl+InsertCopy the selected text to the clipboard.
Ctrl+KDeletes to the end of the line.
Ctrl+VPastes the clipboard text into text edit.
Shift+InsertPastes the clipboard text into text edit.
Ctrl+XDeletes the selected text and copies it to the clipboard.
Shift+DeleteDeletes the selected text and copies it to the clipboard.
Ctrl+ZUndoes the last operation.
Ctrl+YRedoes the last operation.
LeftArrowMoves the cursor one character to the left.
Ctrl+LeftArrowMoves the cursor one word to the left.
RightArrowMoves the cursor one character to the right.
Ctrl+RightArrowMoves the cursor one word to the right.
UpArrowMoves the cursor one line up.
Ctrl+UpArrowMoves the cursor one word up.
DownArrowMoves the cursor one line down.
Ctrl+Down ArrowMoves the cursor one word down.
PageUpMoves the cursor one page up.
PageDownMoves the cursor one page down.
HomeMoves the cursor to the beginning of the line.
Ctrl+HomeMoves the cursor to the beginning of the text.
EndMoves the cursor to the end of the line.
Ctrl+EndMoves the cursor to the end of the text.
Alt+WheelScrolls the page horizontally (the Wheel is the mouse wheel).

To select (mark) text hold down the Shift key whilst pressing one of the movement keystrokes, for example, Shift+Right Arrow will select the character to the right, and Shift+Ctrl+Right Arrow will select the word to the right, etc.

See also QTextDocument, QTextCursor, Application Example, Syntax Highlighter Example, and Rich Text Processing.


Copyright © 2008 Trolltech Trademarks
Qt Jambi 4.3.5_01