![]() |
Home · Overviews · Examples | ![]() |
The QTextEdit class provides a widget that is used to edit and display both plain and rich text. More...
Inherits QAbstractScrollArea.
Inherited by QTextBrowser.
The QTextEdit class provides a widget that is used to edit and display both plain and rich text.
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.
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.
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.
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.
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.
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.
Copyright © 2008 Trolltech | Trademarks | Qt Jambi 4.3.4_01 |