|  | 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
- Using QTextEdit as a Display Widget

- Read-only Key Bindings

- Using QTextEdit as an Editor

- Drag and Drop
- Editing Key Bindings

### 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:

Keypresses | Action
--- | ---
Qt::UpArrow | Moves one line up.
Qt::DownArrow | Moves one line down.
Qt::LeftArrow | Moves one character to the left.
Qt::RightArrow | Moves one character to the right.
PageUp | Moves one (viewport) page up.
PageDown | Moves one (viewport) page down.
Home | Moves to the beginning of the text.
End | Moves to the end of the text.
Alt+Wheel | Scrolls the page horizontally (the Wheel is the mouse wheel).
Ctrl+Wheel | Zooms the text.
Ctrl+A | Selects 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:

Keypresses | Action
--- | ---
Backspace | Deletes the character to the left of the cursor.
Delete | Deletes the character to the right of the cursor.
Ctrl+C | Copy the selected text to the clipboard.
Ctrl+Insert | Copy the selected text to the clipboard.
Ctrl+K | Deletes to the end of the line.
Ctrl+V | Pastes the clipboard text into text edit.
Shift+Insert | Pastes the clipboard text into text edit.
Ctrl+X | Deletes the selected text and copies it to the clipboard.
Shift+Delete | Deletes the selected text and copies it to the clipboard.
Ctrl+Z | Undoes the last operation.
Ctrl+Y | Redoes the last operation.
LeftArrow | Moves the cursor one character to the left.
Ctrl+LeftArrow | Moves the cursor one word to the left.
RightArrow | Moves the cursor one character to the right.
Ctrl+RightArrow | Moves the cursor one word to the right.
UpArrow | Moves the cursor one line up.
Ctrl+UpArrow | Moves the cursor one word up.
DownArrow | Moves the cursor one line down.
Ctrl+Down Arrow | Moves the cursor one word down.
PageUp | Moves the cursor one page up.
PageDown | Moves the cursor one page down.
Home | Moves the cursor to the beginning of the line.
Ctrl+Home | Moves the cursor to the beginning of the text.
End | Moves the cursor to the end of the line.
Ctrl+End | Moves the cursor to the end of the text.
Alt+Wheel | Scrolls 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.