Qt Reference Documentation

Contents

QML TextArea Element

Provides a component for editing and displaying both plain and rich text. More...

  • List of all members, including inherited members

    • Properties

    Methods

    Detailed Description

    The TextArea component displays a block of editable and formatted text. It can display both plain and rich text. TextArea implements the horizontal and vertical scrolling. Scroll bars appear when the content is flicked, or on the focus gain if the content does not fit to view port. TextArea is a superset of TextEdit to implement the Symbian-style look-and-feel. The clipboard support is provided by the cut(), copy(), and paste() functions.

    Note: Copy and paste functionality between a Qt Quick Components application and native Symbian application does not work. For more information, see QTBUG-5701.

    TextArea Basic Examples

    CodeAppearance
     
     TextArea {
     height: 70; width: 160
 }

     TextArea {
     height: 70; width: 160
     placeholderText: "Enter Text Here"
 }

     TextArea {
     height: 70; width: 160
     text: "TextArea"
 }

     TextArea {
     height: 70; width: 160
     text: "TextArea"
     focus: true
 }

     TextArea {
     height: 70; width: 160
     text: "Text Area Text Area Text Area Text Area Text Area Text Area."
 }

    Appearance while draging. See the Touch Interaction section.

     TextArea {
     height: 70; width: 160
     text: "TextArea"
     readOnly: true
 }

     TextArea {
     height: 70; width: 160
     text: "TextArea"
     enabled: false
 }

     TextArea {
     height: 70; width: 160
     text: "TextArea"
     errorHighlight: true
 }

    TextArea Selection in Symbian

    Selected TextAdjust Selection

    Place CursorPaste Menu

    TextArea Behaviors

    Different actions trigger different responses during certain conditions. Touch actions trigger different responses than keyboard actions. Further, responses depend on whether the TextArea is marked as readOnly.

    Touch Interaction

    This table summarizes the Symbian TextArea behaviors for editable text for touch interaction.

    ActionOn TextOn the Cursor / Cursor HandleOn Selected TextOn Selection Handle
    TapPlaces the cursor, and opens virtual keyboard.Opens virtual keyboard.Deselects the current selection, places the cursor, and opens virtual keyboard.Deselects the current selection, places the cursor at the touched position, and opens virtual keyboard.
    Double-tapSelects the word, displays the selection handles on both sides, and shows the context menu (Copy / Cut / Paste).Selects the word, displays the selection handles on both sides, and shows the context menu (Copy / Cut / Paste).Selects the word, displays the selection handles on both sides, and shows the context menu (Copy / Cut / Paste).Selects the word, displays the selection handles on both sides, and shows the context menu (Copy / Cut / Paste).
    Triple-tapSelects all and shows the context menu (Copy / Cut / Paste).Selects all and shows the context menu (Copy / Cut / Paste).Selects all and shows the context menu (Copy / Cut / Paste).Selects all and shows the context menu (Copy / Cut / Paste).
    Tap and HoldPlaces the cursor and displays the magnifier.Displays the magnifier.Deselects the current selection, dismisses the context menu, places the cursor to the touched point, and displays the magnifier.Dismisses the context menu and displays the magnifier
    Release After Tap and HoldShows the context menu (Paste).Dismisses the magnifier and shows the context menu (Paste).Shows the context menu (Paste).Dismisses the magnifier and shows the context menu (Copy / Cut / Paste).
    DragPans the text.Moves the cursor, with the magnifier displayed above.Pans the text.Dismisses the context menu and changes the selection character-by-character, with the magnifier displayed above.
    Release After Drag-Dismisses the magnifier and shows the context menu (Paste).-Dismisses the magnifier and shows the context menu (Copy / Cut / Paste).

    Read-Only Touch Interaction

    This table summarizes the Symbian TextArea behaviors for non-editable text for touch interaction.

    ActionOn TextOn Selected TextOn Selection Handle
    Tap-Deselects the current selection.Deselects the current selection.
    Double-tapSelects the word, displays the selection handles on both sides and shows the context menu (Copy).Selects the word, displays the selection handles on both sides and shows the context menu (Copy).Selects the word, displays the selection handles on both sides and shows the context menu (Copy).
    Triple-tapSelects all and shows the context menu (Copy).Selects all and shows the context menu (Copy).Selects all and shows the context menu (Copy).
    Tap and Hold-Deselects the current selection.Dismisses the context menu and displays the magnifier.
    Release After Tap and Hold--Dismisses the magnifier and shows the context menu (Copy).
    DragPans the text.Pans the text and hides the context menu.Dismisses the context menu and changes the selection character -by-character, with the magnifier displayed above.
    Release After Drag-Shows the context menu (Copy).Dismisses the magnifier and shows the context menu (Copy).

    Keyboard Interaction

    This table summarizes the Symbian TextArea behaviors for editable text for keyboard interaction.

    KeypressesAction
    BackspaceDeletes the character to the left of the cursor.
    LeftMoves the cursor one character to the left.
    RightMoves the cursor one character to the right.
    UpMoves the cursor one line up.
    DownMoves the cursor one line down.
    Shift+LeftSelect the character to the left.
    Shift+RightSelect the character to the right.
    Shift+Ctrl+LeftSelect the word to the left.
    Shift+Ctrl+RightSelect the word to the right.
    Shift+UpSelect the characters to the one line up.
    Shift+DownSelect the characters to the one line down.

    Note: Currently, copy-paste-cut shortcuts don't work on Symbian see QTBUG-5730

    Read-Only Keyboard Interaction

    This table summarizes the Symbian TextArea behaviors for editable text for keyboard interaction.

    KeypressesAction
    LeftMoves the cursor one character to the left.
    RightMoves the cursor one character to the right.
    UpMoves the cursor one line up.
    DownMoves the cursor one line down.
    Shift+LeftSelect the character to the left.
    Shift+RightSelect the character to the right.
    Shift+Ctrl+LeftSelect the word to the left.
    Shift+Ctrl+RightSelect the word to the right.
    Shift+UpSelect the characters to the one line up.
    Shift+DownSelect the characters to the one line down.

    Implicit Size Behaviour

    The text area resizes implicitly to accommodate more text. The maximum sizes are set with the platformMaxImplicitHeight and platformMaxImplicitWidth properties.

    DescriptionMinimum Size
    Minimum implicit size for TextArea is 20 * " " on current font.

    If there is placeholderText defined it's length is the text's minimum implicit size.

    DescriptionGrowth pattern
    With default values TextArea grows indefinitely to right.
     TextArea {
     text: "TextArea TextArea TextArea TextArea"
 }

    Setting platformMaxImplicitWidth defines a wrapping point. When that width is reached TextArea grows indefinitely to bottom.
     TextArea {
     platformMaxImplicitWidth: 200
     text: "TextArea TextArea TextArea TextArea TextArea TextArea TextArea"
 }

    Setting platformMaxImplicitHeight and platformMaxImplicitWidth restricts TextArea to grow only to those values.
     TextArea {
     platformMaxImplicitHeight: 70
     platformMaxImplicitWidth: 200
     text: "TextArea TextArea TextArea TextArea TextArea TextArea TextArea"
 }

    Property Documentation

    read-onlycursorPosition : int

    The position of the cursor in the TextArea.

    See also TextEdit::cursorPosition.


    read-onlyenabled : bool

    Prevent's user interaction from TextArea.


    read-onlyerrorHighlight : bool

    Set's TextArea graphics to show that it contains invalid input.


    read-onlyfont : font

    Font information for the text in the text field.

    See also TextEdit::font.


    read-onlyhorizontalAlignment : int

    read-onlyverticalAlignment : int

    Sets the horizontal and vertical alignment of the text within the TextArea item's width and height. By default, the text is top-left aligned.

    For details of the options, see: TextEdit::horizontalAlignment


    read-onlyinputMethodHints : int

    Settings that indicate what kind of input can be accepted by the textarea. The value is from Qt::InputMethodHints.

    See also TextEdit::inputMethodHints.


    read-onlyplaceholderText : string

    The text that is shown in the text area before the user enters any text. When the user starts entering text, the placeholder text is hidden.


    read-onlyplatformMaxImplicitHeight : double

    Defines the maximum height that the TextArea can grow.

    The default value for this property is -1 and the height is allowed to grow infinitely.

    If a height is explicitly set then this property has no effect.

    See also platformMaxImplicitWidth.


    read-onlyplatformMaxImplicitWidth : double

    Defines the maximum width that the TextArea can grow.

    The default value for this property is -1, which allows the widthto grow infinitely.

    If a width is explicitly set then this property has no effect.

    See also platformMaxImplicitHeight.


    read-onlyreadOnly : bool

    If true, the text field can only be viewed and cannot be edited.

    If this is false, the text field can be edited.

    See also TextEdit::readOnly.


    read-onlyselectedText : string

    This read-only property provides the text that is currently selected in the text field.

    See also TextEdit::selectedText.


    read-onlyselectionEnd : int

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

    See also selectionstart, selectedText, cursorPosition, and TextEdit::selectionEnd.


    read-onlyselectionStart : int

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

    See also selectionEnd, selectedText, cursorPosition, and TextEdit::selectionStart.


    read-onlytext : string

    The text that has been entered into the text field.


    read-onlytextFormat : int

    This determines if the text is displayed as rich text or plain text. By default it will and determine if the text is rich text or plain text and display it appropriately.

    See TextEdit::textFormat for the enumeration details.


    read-onlywrapMode : int

    This determines if text in the TextArea is wrapped or not.

    See TextEdit::wrapMode for details of the different modes.


    Method Documentation

    TextArea::copy ()

    Copies the currently selected text to the system clipboard.

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


    TextArea::cut ()

    Moves the currently selected text to the system clipboard.

    See also TextEdit::cut().


    TextArea::paste ()

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

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


    TextArea::positionAt ( x, y )

    Returns the character position at x pixels from the left edge of the text field and y pixels from the top edge of the text field.

    See also TextEdit::positionAt().


    TextArea::positionToRectangle ( pos )

    Returns the rectangle that the cursor would occupy if it was placed at pos character position.

    This is similar to setting the cursorPosition and then querying the cursor rectangle, but the cursorPosition is not changed.

    See also cursorPosition and TextEdit::positionToRectangle().


    TextArea::select ( start, end )

    Causes the text from start to end to be selected.

    See also selectionStart, selectionEnd, and TextEdit::select().


    TextArea::selectAll ()

    Causes all text in the text field to be selected.

    See also TextEdit::selectAll().


    TextArea::selectWord ()

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

    See also TextEdit::selectWord().


    © 2008-2011 Nokia Corporation and/or its subsidiaries. Nokia, Qt and their respective logos are trademarks of Nokia Corporation in Finland and/or other countries worldwide.

    All other trademarks are property of their respective owners. Privacy Policy


    Licensees holding valid Qt Commercial licenses may use this document in accordance with the Qt Commercial License Agreement provided with the Software or, alternatively, in accordance with the terms contained in a written agreement between you and Nokia.

    Alternatively, this document may be used under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation.