Classes - Annotated - Tree - Functions - Home - Structure

QTextEdit Class Reference

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

#include <qtextedit.h>

Inherits QTextView.

Inherited by QMultiLineEdit.

List of all member functions.

Public Members

Public Slots

Signals

Properties

Protected Members


Detailed Description

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

QTextEdit is an advanced WYSIWYG editor supporting rich text formatting. It is optimized to handle large documents and to respond quickly to user input.

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

The text edit documentation uses the following concepts:

QTextEdit extends QTextView with keyboard and mouse handling for user input. QTextEdit provides functions to change the text and its formatting.

The text is set or replaced using setText() which deletes any existing text and replaces it with the text passed in the setText() call. Text can be inserted with insert(), paste() and pasteSubType(). 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).

The current format's attributes are set with setItalic(), setBold(), setUnderline(), setFamily() (font family), setPointSize(), setColor() and setCurrentFont(). The current paragraph's style is set with setParagType() and its alignment is set with setAlignment().

Internally QTextEdit works on paragraphs and characters. A paragraph is a formatted string which is word-wrapped to fit into the width of the widget. Paragraphs are separated by hard line breaks. Each character has its own attributes, for example, font and color.

Use setSelection() to programmatically select text. The setSelectionAttributes() function is used to set how selected text should be displayed. The currently selected text's position is available using QTextView::getSelection() and the selected text itself is returned by QTextView::selectedText(). The selection can be copied to the clipboard with copy(), or cut to the clipboard with cut(). It can be deleted with removeSelectedText(). The entire text can be selected (or unselected) using selectAll().

Set and get the position of the cursor with setCursorPosition() and getCursorPosition() respectively. When the cursor is moved, the signals currentFontChanged(), currentColorChanged() and currentAlignmentChanged() are emitted to reflect the font, color and alignment at the new cursor position.

If the text changes, the textChanged() signal is emitted, and if the user inserts a new line by pressing Return or Enter, returnPressed() is emitted.

QTextEdit provides command-based undo/redo. To set the depth of the command history use setUndoDepth() which defaults to 100 steps. To undo or redo the last operation call undo() or redo(). The signals undoAvailable() and redoAvailable() indicate whether the undo and redo operations can be executed.

The indent() function is used to reindent a paragraph. It is useful for code editors, for example in Qt Designer's code editor Ctrl+I invokes the indent() function.

Loading and saving text is achieved using setText() and text(), for example:

    QFile file( fileName ); // Read the text from a file
    if ( file.open( IO_ReadOnly ) ) {
        QTextStream ts( &file );
        textEdit->setText( ts.read() );
    }
  
    QFile file( fileName ); // Write the text to a file
    if ( file.open( IO_WriteOnly ) ) {
        QTextStream ts( &file );
        ts << textEdit->text();
        textEdit->setModified( FALSE );
    }
  

The list of key-bindings which are implemented for editing:

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.

By default the text edit widget operates in insert mode so all text that the user enters is inserted into the text edit and any text to the right of the cursor is moved out of the way. The mode can be changed to overwrite, where new text overwrites any text to the right of the cursor, using setOverwriteMode().


Member Type Documentation

QTextEdit::KeyboardAction

This enum is used by doKeyboardAction() to specify which action should be executed:

QTextEdit::MoveDirection

This enum is used by moveCursor() to specify in which direction the cursor should be moved:


Member Function Documentation

QTextEdit::QTextEdit ( QWidget * parent = 0, const char * name = 0 )

Constructs a QTextEdit. The parent and name arguments are as for QWidget.

int QTextEdit::alignment () const

Returns the alignment of the current paragraph.

See also setAlignment().

bool QTextEdit::bold () const

Returns TRUE if the current format is bold; otherwise returns FALSE.

See also setBold().

void QTextEdit::clear () [virtual slot]

Deletes all the text in the text edit.

See also cut() and removeSelectedText().

Example: mdi/application.cpp.

QColor QTextEdit::color () const

Returns the color of the current format.

See also setColor().

void QTextEdit::currentAlignmentChanged ( int a ) [signal]

This signal is emitted if the alignment of the current paragraph has changed.

The new alignment is a.

See also setAlignment().

void QTextEdit::currentColorChanged ( const QColor & c ) [signal]

This signal is emitted if the color of the current format has changed.

The new color is c.

See also setColor().

void QTextEdit::currentFontChanged ( const QFont & f ) [signal]

This signal is emitted if the font of the current format has changed.

The new font is f.

See also setCurrentFont().

void QTextEdit::cursorPositionChanged ( QTextCursor * c ) [signal]

This signal is emitted if the position of the cursor changed. c points to the text cursor object.

See also setCursorPosition().

void QTextEdit::cut () [virtual slot]

Copies the selected text to the clipboard and deletes it from the text edit.

If there is no selected text nothing happens.

See also QTextView::copy(), paste() and pasteSubType().

void QTextEdit::del () [virtual slot]

If there is some selected text it is deleted. If there is no selected text the character to the right of the text cursor is deleted.

See also removeSelectedText() and cut().

void QTextEdit::doKeyboardAction ( KeyboardAction action ) [protected]

Executes the keyboard action action. This is normally called by a key event handler.

void QTextEdit::ensureCursorVisible () [protected]

Ensures that the cursor is visible by scrolling the text edit if necessary.

See also setCursorPosition().

QString QTextEdit::family () const

Returns the font family of the current format.

See also setFamily(), setCurrentFont() and setPointSize().

QFont QTextEdit::font () const

Returns the font of the current format.

See also setCurrentFont().

Examples: action/application.cpp, application/application.cpp, mdi/application.cpp and qwerty/qwerty.cpp.

void QTextEdit::getCursorPosition ( int & parag, int & index ) const

This function sets the parag and index parameters to the current cursor position.

See also setCursorPosition().

bool QTextEdit::getFormat ( int para, int index, QFont * font, QColor * color ) [virtual]

This function gets the format of the character at position index in paragraph para. Sets font to the character's font and color to the character's color.

Returns FALSE if para or index is out of range otherwise returns TRUE.

void QTextEdit::indent () [virtual slot]

Re-indents the current paragraph.

void QTextEdit::insert ( const QString & text, bool indent = FALSE, bool checkNewLine = TRUE, bool removeSelected = TRUE ) [virtual]

Inserts text at the current cursor position. If indent is TRUE, the paragraph is re-indented. If checkNewLine is TRUE, newline characters in text result in hard line breaks (i.e. new paragraphs). If checkNewLine is FALSE the behaviour of the editor is undefined if the text contains newlines. If removeSelected is TRUE, any selected text is removed before the text is inserted.

See also paste() and pasteSubType().

bool QTextEdit::isOverwriteMode () const

Returns the text edit's overwrite mode. See the "overwriteMode" property for details.

bool QTextEdit::italic () const

Returns TRUE if the current format is italic; otherwise returns FALSE.

See also setItalic().

void QTextEdit::modificationChanged ( bool m ) [signal]

This signal is emitted when the modification of the document changed. If m is TRUE, the document was modified, otherwise the modification state has been reset to unmodified.

See also modified.

void QTextEdit::moveCursor ( MoveDirection direction, bool shift, bool control ) [protected]

Moves the text cursor in direction. As this is normally used by some key event handler, the state of the Shift and Ctrl keys will influence how the cursor moves. For example, Left Arrow moves one character left, but Ctrl+Left Arrow moves one word left.

void QTextEdit::moveCursor ( MoveDirection direction, bool control ) [protected]

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

void QTextEdit::paste () [virtual slot]

Pastes the text from the clipboard into the text edit at the current cursor position. Only plain text is pasted.

If there is no text in the clipboard nothing happens.

See also pasteSubType(), cut() and QTextView::copy().

void QTextEdit::pasteSubType ( const QCString & subtype ) [virtual slot]

Pastes the text with format subtype from the clipboard into the text edit at the current cursor position. The subtype can be "plain" or "html".

If there is no text with format subtype in the clipboard nothing happens.

See also paste(), cut() and QTextView::copy().

void QTextEdit::placeCursor ( const QPoint & pos, QTextCursor * c = 0 ) [protected]

Places the cursor c at the character which is closest to pos (in contents coordinates). If c is 0, the default text cursor is used.

See also setCursorPosition().

int QTextEdit::pointSize () const

Returns the point size of the font of the current format.

See also setFamily(), setCurrentFont() and setPointSize().

void QTextEdit::redo () [virtual slot]

Redoes the last operation.

If there is no operation to redo, e.g. there is no redo step in the undo/redo history, nothing happens.

See also redoAvaliable(), undo() and undoDepth.

void QTextEdit::redoAvailable ( bool yes ) [signal]

This signal is emitted when the availability of redo changes. If yes is TRUE, then redo() will work until redoAvailable( FALSE ) is next emitted.

See also redo() and undoDepth.

void QTextEdit::removeSelectedText () [virtual slot]

Deletes the selected text. If there is no selected text nothing happens.

void QTextEdit::returnPressed () [signal]

This signal is emitted if the user pressed the RETURN or the ENTER key.

void QTextEdit::setAlignment ( int a ) [virtual slot]

Sets the alignment of the current paragraph to a. Valid alignments are Qt::AlignLeft, Qt::AlignRight and Qt::AlignJustify. (See Qt::AlignmentFlags.)

See also setParagType().

void QTextEdit::setBold ( bool b ) [virtual slot]

If b is TRUE sets the current format to bold; otherwise sets the current format to non-bold.

See also bold().

void QTextEdit::setColor ( const QColor & c ) [virtual slot]

Sets the color of the current format to c.

See also color().

Example: action/actiongroup/editor.cpp.

void QTextEdit::setCurrentFont ( const QFont & f ) [virtual slot]

Sets the font of the current format to f.

See also font(), setPointSize() and setFamily().

void QTextEdit::setCursorPosition ( int parag, int index ) [virtual slot]

Sets the cursor to position index in paragraph parag.

See also getCursorPosition().

void QTextEdit::setFamily ( const QString & f ) [virtual slot]

Sets the font family of the current format to f.

See also family() and setCurrentFont().

void QTextEdit::setFont ( const QFont & f ) [virtual slot]

This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

Use setCurrentFont() instead.

Example: qwerty/qwerty.cpp.

Reimplemented from QTextView.

void QTextEdit::setItalic ( bool b ) [virtual slot]

If b is TRUE sets the current format to italic; otherwise sets the current format to non-italic.

See also italic().

void QTextEdit::setOverwriteMode ( bool b ) [virtual slot]

Sets the text edit's overwrite mode to b. See the "overwriteMode" property for details.

void QTextEdit::setParagType ( QStyleSheetItem::DisplayMode dm, QStyleSheetItem::ListStyle listStyle ) [virtual slot]

Sets the paragraph style of the current paragraph to dm. If dm is QStyleSheetItem::DisplayListItem, the type of the list item is set to listStyle.

See also setAlignment().

void QTextEdit::setPointSize ( int s ) [virtual slot]

Sets the point size of the current format to s.

Note that if s is zero or negative, the behaviour of this function is not defined.

See also pointSize(), setCurrentFont() and setFamily().

void QTextEdit::setSelection ( int parag_from, int index_from, int parag_to, int index_to, int selNum = 0 ) [virtual slot]

Sets a selection which starts at position index_from in paragraph parag_from and ends position index_to in paragraph parag_to.

Uses the selection settings of selection selNum. If this is 0, this is the default selection.

See also getSelection() and selectedText.

void QTextEdit::setSelectionAttributes ( int selNum, const QColor & back, bool invertText ) [virtual slot]

Sets the background color of selection selNum to back and specifies whether the text of this selection should be inverted with invertText.

void QTextEdit::setUnderline ( bool b ) [virtual slot]

If b is TRUE sets the current format to underline; otherwise sets the current format to non-underline.

See also underline().

void QTextEdit::setUndoDepth ( int d ) [virtual slot]

Sets the depth of the undo history to d. See the "undoDepth" property for details.

QTextCursor * QTextEdit::textCursor () const [protected]

Returns the text edit's text cursor. QTextCursor is not in the public API, but in special circumstances you might wish to use it. Note however that the API might change in an incompatible manner in the future.

bool QTextEdit::underline () const

Returns TRUE if the current format is underlined; otherwise returns FALSE.

See also setUnderline().

void QTextEdit::undo () [virtual slot]

Undoes the last operation.

If there is no operation to undo, e.g. there is no undo step in the undo/redo history, nothing happens.

See also undoAvaliable(), redo() and undoDepth.

void QTextEdit::undoAvailable ( bool yes ) [signal]

This signal is emitted when the availability of undo changes. If yes is TRUE, then undo() will work until undoAvailable( FALSE ) is next emitted.

See also undo() and undoDepth.

int QTextEdit::undoDepth () const

Returns the depth of the undo history. See the "undoDepth" property for details.


Property Documentation

bool overwriteMode

This property holds the text edit's overwrite mode.

If TRUE, the editor is in overwrite mode, i.e. characters entered by the user overwrite any characters to the right of the cursor position. If FALSE characters entered by the user are inserted with any characters to the right being moved out of the way.

Set this property's value with setOverwriteMode() and get this property's value with isOverwriteMode().

int undoDepth

This property holds the depth of the undo history.

The maximum number of steps in the undo/redo history.

Set this property's value with setUndoDepth() and get this property's value with undoDepth().

See also undo() and redo().


Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):


This file is part of the Qt toolkit, copyright © 1995-2000 Trolltech, all rights reserved.


Copyright © 2000 TrolltechTrademarks
Qt version main-beta1