Qt 5.6 | Qt Quick Controls | QML Types | TextArea QML Type

Qt 5.6.2 Reference Documentation

# TextArea QML Type

Displays multiple lines of editable formatted text. More...

Import Statement: | import QtQuick.Controls 1.4
Since: | Qt 5.1
Inherits: | ScrollView

- List of all members, including inherited members

## Properties

- activeFocusOnPress : bool
- backgroundVisible : bool
- baseUrl : url
- canPaste : bool
- canRedo : bool
- canUndo : bool
- contentHeight : real
- contentWidth : real
- cursorPosition : int
- cursorRectangle : rect
- effectiveHorizontalAlignment : enumeration
- font : font
- horizontalAlignment : enumeration
- hoveredLink : string
- inputMethodComposing : bool
- inputMethodHints : enumeration
- length : int
- lineCount : int
- menu : Component
- readOnly : bool
- selectByKeyboard : bool
- selectByMouse : bool
- selectedText : string
- selectionEnd : int
- selectionStart : int
- tabChangesFocus : bool
- text : string
- textColor : color
- textDocument : TextDocument
- textFormat : enumeration
- textMargin : real
- verticalAlignment : enumeration
- wrapMode : enumeration

## Signals

- editingFinished()
- linkActivated(string link)
- linkHovered(string link)

## Methods

- void append(string text)
- void copy()
- void cut()
- void deselect()
- string getFormattedText(int start, int end)
- string getText(int start, int end)
- void insert(int position, string text)
- bool isRightToLeft(int start, int end)
- void moveCursorSelection(int position, SelectionMode mode)
- void paste()
- int positionAt(int x, int y)
- rectangle positionToRectangle(position)
- void redo()
- string remove(int start, int end)
- void select(int start, int end)
- void selectAll()
- void selectWord()
- void undo()

## Detailed Description

It can display both plain and rich text. For example:

      TextArea {
          width: 240
          text:
              "Lorem ipsum dolor sit amet, consectetur adipisicing elit, " +
              "sed do eiusmod tempor incididunt ut labore et dolore magna " +
              "aliqua. Ut enim ad minim veniam, quis nostrud exercitation " +
              "ullamco laboris nisi ut aliquip ex ea commodo cosnsequat. ";
      }

Clipboard support is provided by the cut(), copy(), and paste() functions, and the selection can be handled in a traditional "mouse" mechanism by setting selectByMouse, or handled completely from QML by manipulating selectionStart and selectionEnd, or using selectAll() or selectWord().

You can translate between cursor positions (characters from the start of the document) and pixel points using positionAt() and positionToRectangle().

You can create a custom appearance for a TextArea by assigning a TextAreaStyle.

See also TextField and TextEdit.

## Property Documentation

activeFocusOnPress : bool

Whether the TextEdit should gain active focus on a mouse press. By default this is set to true.

backgroundVisible : bool

This property determines if the background should be filled or not.

The default value is `true`.

baseUrl : url

This property specifies a base URL which is used to resolve relative URLs within the text.

The default value is the url of the QML file instantiating the TextArea item.

[read-only] canPaste : bool

Returns true if the TextArea is writable and the content of the clipboard is suitable for pasting into the TextArea.

[read-only] canRedo : bool

Returns true if the TextArea is writable and there are undone operations that can be redone.

[read-only] canUndo : bool

Returns true if the TextArea is writable and there are previous operations that can be undone.

[read-only] contentHeight : real

The height of the text content.

This QML property was introduced in QtQuick.Controls 1.3.

[read-only] contentWidth : real

The width of the text content.

This QML property was introduced in QtQuick.Controls 1.3.

cursorPosition : int

The position of the cursor in the TextArea.

[read-only] cursorRectangle : rect

The rectangle where the text cursor is rendered within the text area.

This QML property was introduced in QtQuick.Controls 1.3.

[read-only] effectiveHorizontalAlignment : enumeration

Gets the effective horizontal alignment of the text within the TextArea item's width.

To set/get the default horizontal alignment of TextArea, use the property `horizontalAlignment`.

font : font

The font of the TextArea.

horizontalAlignment : enumeration

Sets the alignment of the text within the TextArea item's width.

By default, the horizontal text alignment follows the natural alignment of the text, for example, text that is read from left to right will be aligned to the left.

The valid values for `horizontalAlignment` are:

- TextEdit.AlignLeft (Default)
- TextEdit.AlignRight
- TextEdit.AlignHCenter

When using the attached property LayoutMirroring::enabled to mirror application layouts, the horizontal alignment of text will also be mirrored. However, the property `horizontalAlignment` will remain unchanged. To query the effective horizontal alignment of TextArea, use the read-only property `effectiveHorizontalAlignment`.

[read-only] hoveredLink : string

This property contains the link string when user hovers a link embedded in the text. The link must be in rich text or HTML format and the link string provides access to the particular link.

This QML property was introduced in QtQuick.Controls 1.1.

[read-only] inputMethodComposing : bool

This property holds whether the TextArea has partial text input from an input method.

While it is composing an input method may rely on mouse or key events from the TextArea to edit or commit the partial text. This property can be used to determine when to disable events handlers that may interfere with the correct operation of an input method.

This QML property was introduced in QtQuick.Controls 1.3.

inputMethodHints : enumeration

Provides hints to the input method about the expected content of the text edit, and how it should operate.

The value is a bit-wise combination of flags or Qt.ImhNone if no hints are set.

The default value is `Qt.ImhNone`.

Flags that alter behavior are:

- Qt.ImhHiddenText - Characters should be hidden, as is typically used when entering passwords.
- Qt.ImhSensitiveData - Typed text should not be stored by the active input method in any persistent storage like predictive user dictionary.
- Qt.ImhNoAutoUppercase - The input method should not try to automatically switch to upper case when a sentence ends.
- Qt.ImhPreferNumbers - Numbers are preferred (but not required).
- Qt.ImhPreferUppercase - Upper case letters are preferred (but not required).
- Qt.ImhPreferLowercase - Lower case letters are preferred (but not required).
- Qt.ImhNoPredictiveText - Do not use predictive text (i.e. dictionary lookup) while typing.
- Qt.ImhDate - The text editor functions as a date field.
- Qt.ImhTime - The text editor functions as a time field.

Flags that restrict input (exclusive flags) are:

- Qt.ImhDigitsOnly - Only digits are allowed.
- Qt.ImhFormattedNumbersOnly - Only number input is allowed. This includes decimal point and minus sign.
- Qt.ImhUppercaseOnly - Only upper case letter input is allowed.
- Qt.ImhLowercaseOnly - Only lower case letter input is allowed.
- Qt.ImhDialableCharactersOnly - Only characters suitable for phone dialing are allowed.
- Qt.ImhEmailCharactersOnly - Only characters suitable for email addresses are allowed.
- Qt.ImhUrlCharactersOnly - Only characters suitable for URLs are allowed.

Masks:

- Qt.ImhExclusiveInputMask - This mask yields nonzero if any of the exclusive flags are used.

[read-only] length : int

Returns the total number of plain text characters in the TextArea item.

As this number doesn't include any formatting markup, it may not be the same as the length of the string returned by the text property.

This property can be faster than querying the length the text property as it doesn't require any copying or conversion of the TextArea's internal string data.

[read-only] lineCount : int

Returns the total number of lines in the TextArea item.

menu : Component

This property contains the edit Menu for working with text selection. Set it to `null` if no menu is wanted.

This QML property was introduced in QtQuick.Controls 1.3.

See also Menu.

readOnly : bool

Whether the user can interact with the TextArea item.

The difference from a disabled text field is that it will appear to be active, and text can be selected and copied.

If this property is set to `true`, the text cannot be edited by user interaction.

By default this property is `false`.

selectByKeyboard : bool

This property determines if the user can select the text with the keyboard.

If set to `true`, the user can use the keyboard to select the text even if the editor is read-only. If set to `false`, the user cannot use the keyboard to select the text even if the editor is editable.

The default value is `true` when the editor is editable, and `false` when read-only.

See also readOnly.

selectByMouse : bool

This property determines if the user can select the text with the mouse.

The default value is `true`.

[read-only] selectedText : string

This read-only property provides the text currently selected in the text edit.

[read-only] selectionEnd : int

The cursor position after the last character in the current selection.

This property is read-only. To change the selection, use select(start,end), selectAll(), or selectWord().

See also selectionStart, cursorPosition, and selectedText.

[read-only] selectionStart : int

The cursor position before the first character in the current selection.

This property is read-only. To change the selection, use select(start,end), selectAll(), or selectWord().

See also selectionEnd, cursorPosition, and selectedText.

tabChangesFocus : bool

This property holds whether Tab changes focus, or is accepted as input.

Defaults to `false`.

text : string

The text to display. If the text format is AutoText the text edit will automatically determine whether the text should be treated as rich text. This determination is made using Qt::mightBeRichText().

textColor : color

The text color.

      TextArea { textColor: "orange" }

textDocument : TextDocument

This property exposes the QQuickTextDocument of this TextArea.

See also TextEdit::textDocument.

textFormat : enumeration

The way the text property should be displayed.

- TextEdit.AutoText
- TextEdit.PlainText
- TextEdit.RichText

The default is TextEdit.PlainText. If the text format is TextEdit.AutoText the text edit will automatically determine whether the text should be treated as rich text. This determination is made using Qt::mightBeRichText().

textMargin : real

The margin, in pixels, around the text in the TextArea.

This QML property was introduced in QtQuick.Controls 1.1.

verticalAlignment : enumeration

Sets the alignment of the text within the TextArea item's height.

The valid values for `verticalAlignment` are:

- TextEdit.AlignTop
- TextEdit.AlignBottom
- TextEdit.AlignVCenter (Default)

wrapMode : enumeration

Set this property to wrap the text to the TextArea item's width.

- TextEdit.NoWrap - no wrapping will be performed.
- TextEdit.WordWrap (default) - wrapping is done on word boundaries only.
- TextEdit.WrapAnywhere - wrapping is done at any point on a line, even if it occurs in the middle of a word.
- TextEdit.Wrap - if possible, wrapping occurs at a word boundary; otherwise it will occur at the appropriate point on the line, even in the middle of a word.

## Signal Documentation

editingFinished()

This signal is emitted when the text area loses focus.

The corresponding handler is `onEditingFinished`.

This QML signal was introduced in QtQuick.Controls 1.5.

linkActivated(string link)

This signal is emitted when the user clicks on a link embedded in the text. The link must be in rich text or HTML format and the link string provides access to the particular link.

The corresponding handler is `onLinkActivated`.

linkHovered(string link)

This signal is emitted when the user hovers a link embedded in the text. The link must be in rich text or HTML format and the link string provides access to the particular link.

The corresponding handler is `onLinkHovered`.

This QML signal was introduced in QtQuick.Controls 1.1.

See also hoveredLink.

## Method Documentation

void append(string text)

Appends string as a new line to the end of the text area.

void copy()

Copies the currently selected text to the system clipboard.

void cut()

Moves the currently selected text to the system clipboard.

void deselect()

Removes active text selection.

string getFormattedText(int start, int end)

Returns the section of text that is between the start and end positions.

The returned text will be formatted according to the textFormat property.

string getText(int start, int end)

Returns the section of text that is between the start and end positions.

The returned text does not include any rich text formatting.

void insert(int position, string text)

Inserts text into the TextArea at position.

bool isRightToLeft(int start, int end)

Returns true if the natural reading direction of the editor text found between positions start and end is right to left.

void moveCursorSelection(int position, SelectionMode mode = TextEdit.SelectCharacters)

Moves the cursor to position and updates the selection according to the optional mode parameter. (To only move the cursor, set the cursorPosition property.)

When this method is called it additionally sets either the selectionStart or the selectionEnd (whichever was at the previous cursor position) to the specified position. This allows you to easily extend and contract the selected text range.

The selection mode specifies whether the selection is updated on a per character or a per word basis. If not specified the selection mode will default to TextEdit.SelectCharacters.

- TextEdit.SelectCharacters - Sets either the selectionStart or selectionEnd (whichever was at the previous cursor position) to the specified position.
- TextEdit.SelectWords - Sets the selectionStart and selectionEnd to include all words between the specified position and the previous cursor position. Words partially in the range are included.

For example, take this sequence of calls:

      cursorPosition = 5
      moveCursorSelection(9, TextEdit.SelectCharacters)
      moveCursorSelection(7, TextEdit.SelectCharacters)

This moves the cursor to the 5th position, extends the selection end from 5 to 9, and then retracts the selection end from 9 to 7, leaving the text from the 5th position to the 7th position selected (the 6th and 7th characters).

The same sequence with TextEdit.SelectWords will extend the selection start to a word boundary before or on the 5th position, and extend the selection end to a word boundary on or past the 9th position.

void paste()

Replaces the currently selected text by the contents of the system clipboard.

int positionAt(int x, int y)

Returns the text position closest to pixel position (x, y).

Position 0 is before the first character, position 1 is after the first character but before the second, and so on until position text.length, which is after all characters.

rectangle positionToRectangle(position)

Returns the rectangle at the given position in the text. The x, y, and height properties correspond to the cursor that would describe that position.

void redo()

Redoes the last operation if redo is available.

string remove(int start, int end)

Removes the section of text that is between the start and end positions from the TextArea.

void select(int start, int end)

Causes the text from start to end to be selected.

If either start or end is out of range, the selection is not changed.

After calling this, selectionStart will become the lesser and selectionEnd will become the greater (regardless of the order passed to this method).

See also selectionStart and selectionEnd.

void selectAll()

Causes all text to be selected.

void selectWord()

Causes the word closest to the current cursor position to be selected.

void undo()

Undoes the last operation if undo is available. Deselects any current selection, and updates the selection start to the current cursor position.