Qt Reference Documentation

QML TextField Element

Provides a component for editing and displaying a single line of plain text. More...

  • List of all members, including inherited members
  • Properties

    Methods

    Detailed Description

    The TextField component displays a single line of editable plain text. You can place input constraints for a TextField component, for example, through a validator or inputMask. You can also set echoMode to an appropriate value for making the TextField suitable for a password input field. If the text content is longer than the TextField view port, the user can scroll the field horizontally. TextField is a superset of TextInput and it implements the Symbian-style look-and-feel. The clipboard support is provided by the cut(), copy(), and paste() functions.

    Note: Copy-Paste between a qt-components application and native Symbian application does not work. For more information, see QTBUG-5701.

    TextField Basic Examples

    CodeAppearance
     TextField {
         width: 160
     }

     TextField {
         width: 160
         placeholderText: "Enter Text Here"
     }

     TextField {
         width: 160
         text: "TextField"
     }

     TextField {
         width: 160
         text: "TextField"
         focus: true
     }

     TextField {
         width: 160
         text: "Text Field Text Field Text Field Text Field Text Field Text Field."
     }

    Appearance while draging. See the Touch Interaction section.

     TextField {
         width: 160
         text: "TextField"
         readOnly: true
     }

     TextField {
         width: 160
         text: "TextField"
         enabled: false
     }

     TextField {
         width: 160
         text: "TextField"
         validator: IntValidator{bottom: 0; top: 100}
     }

     TextField {
         width: 160
         text: "TextField"
         errorHighlight: true
     }

     TextField {
         width: 160
         text: "TextField"
         echoMode: TextInput.Password
     }

    TextField Selection in Symbian

    Different options become available when a selecting a piece of text.

    Selected TextAdjust Selection

    Place CursorPaste Menu

    TextField Behaviors

    Different user actions trigger different TextField responses during certain scenarios. As well, touch actions trigger different responses than keyboard actions. Further, responses depend on whether the TextField is marked as readOnly.

    Touch Interaction

    This table summarizes the Symbian TextField 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 TextField 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 TextField 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.

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

    Read-Only Keyboard Interaction

    This table summarizes the Symbian TextField 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.

    Custom buttons to TextField

    The following section shows exmaples how to add custom button/operations over TextField component using platformLeftMargin / platformRightMargin.

    TextField with Clear Button

     TextField {
         id: clearable
         text: "Clearable TextField"
         platformRightMargin: clearText.width + platformStyle.paddingMedium * 2
         width: 210
    
         Image {
             anchors { top: parent.top; right: parent.right; margins: platformStyle.paddingMedium }
             id: clearText
             fillMode: Image.PreserveAspectFit
             smooth: true; visible: clearable.text
             source: "clear.svg"
             height: parent.height - platformStyle.paddingMedium * 2
             width: parent.height - platformStyle.paddingMedium * 2
    
             MouseArea {
                 id: clear
                 anchors { horizontalCenter: parent.horizontalCenter; verticalCenter: parent.verticalCenter }
                 height: clearable.height; width: clearable.height
                 onClicked: {
                     clearable.text = ""
                     clearable.forceActiveFocus()
                 }
             }
         }
     }

    TextField with Custom Operation

     TextField {
         id: customOperation
         placeholderText: "Custom operation"
         platformRightMargin: addText.width + platformStyle.paddingMedium
         width: 260
    
         Image {
             id: addText
             anchors { top: parent.top; right: parent.right }
             smooth: true
             fillMode: Image.PreserveAspectFit
             source: "add.svg"
             height: parent.height; width: parent.height
    
             MouseArea {
                 id: add
                 anchors.fill: parent
                 onClicked: textSelection.open()
             }
    
             SelectionDialog {
                 id: textSelection
                 titleText: "Preset Texts"
                 selectedIndex: -1
                 model: ListModel {
                     ListElement { name: "Lorem ipsum." }
                     ListElement { name: "Lorem ipsum dolor." }
                     ListElement { name: "Lorem ipsum dolor sit." }
                 }
    
                 onAccepted: {
                     customOperation.text = textSelection.model.get(textSelection.selectedIndex).name
                     customOperation.forceActiveFocus()
                 }
    
                 onRejected: selectedIndex = -1
             }
         }
     }

    TextField with Search

     TextField {
         id: searchOperation
         text: "Search..."
         platformLeftMargin: search.width + platformStyle.paddingSmall
         width: 150
    
         Image {
             id: search
             anchors { top: parent.top; left: parent.left; margins: platformStyle.paddingMedium }
             smooth: true
             fillMode: Image.PreserveAspectFit
             source: "search.svg"
             height: parent.height - platformStyle.paddingMedium * 2
             width: parent.height - platformStyle.paddingMedium * 2
         }
     }

    Property Documentation

    read-onlyacceptableInput : bool

    Indicates whether or not the current text the user enters is acceptable as a final string. The value is true in the following cases:

    • The validator or input mask is not set.
    • The text is acceptable to the set validator or input mask.

    Otherwise the value is false.

    See also inputMask, validator, and TextInput::acceptableInput.


    read-onlycursorPosition : int

    The position of the cursor in the TextField.

    See also TextInput::cursorPosition.


    read-onlyechoMode : int

    Specifies how the text is displayed when the user enters text into the text field. For example, you can set the echo mode to Password so that the entered text is shown as asterisks. The possible values are the same as those defined for TextInput::echoMode.

    See also TextInput::echoMode.


    read-onlyenabled : bool

    Setting to false will prevent user interaction with the TextField. The default value is \true.


    read-onlyerrorHighlight : bool

    Set's TextField graphics to show that it contains invalid input. By default, this property responds to a validator.

    See the TextField Basic Examples section for an example.


    read-onlyfont : font

    Font information for the text in the text field. The possible values are the same as those defined for TextInput::font.

    See also TextInput::font.


    read-onlyinputMask : string

    Allows you to restrict what the user can enter into the text field. TextField, TextInput, and QLineEdit use the same input mask. See QLineEdit::inputMask for details how to define the input mask.

    See also acceptableInput, validator, and TextInput::inputMask.


    read-onlyinputMethodHints : int

    Settings that indicate what kind of input the text field accepts. The possible values are the same as those defined for Qt::InputMethodHints.

    See also TextInput::inputMethodHints.


    read-onlymaximumLength : int

    The maximum permitted length of the text in the TextField. If the text is too long, it is truncated at the limit. By default, this property contains a value of 32767. Shares the same values as those defined for TextInput::maximumLength.

    See also TextInput::font.


    read-onlyplaceholderText : string

    The text that is shown in the text field as long as it has not the focus if the value of the text property is an empty string. The placeholder text is shown as greyed-out. When the field gets the focus, the placeholder text disappears. The default value of placeholderText is an empty string.

    See the TextField Basic Examples section for an example.


    read-onlyplatformLeftMargin : real

    Used to set the position of TextField left marigin. By setting the margin user can adjust space between TextFields left side and text content start position.


    read-onlyplatformRightMargin : real

    Used to set the position of TextField right marigin. By setting the margin user can adjust space between TextFields right side and text content end position.


    read-onlyreadOnly : bool

    If readOnly is true, the user can see the text in the text field but cannot edit it. If false, the user can also edit the text in the text field.

    See the TextField Basic Examples section for an example.

    See also TextInput::readOnly.


    read-onlyselectedText : string

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

    See also TextInput::selectedText.


    read-onlyselectionEnd : int

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

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


    read-onlyselectionStart : int

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

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


    read-onlytext : string

    The string content of the text field. The default value is an empty string.

    See also placeholderText.


    read-onlyvalidator : validator

    Allows you to set a validator (IntValidator, DoubleValidator or RegExpValidator) for the text field. See TextInput::validator for details.

    See also acceptableInput and inputMask.


    Method Documentation

    TextField::copy ()

    Copies the currently selected text to the system clipboard.

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


    TextField::cut ()

    Moves the currently selected text to the system clipboard.

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


    TextField::paste ()

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

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


    TextField::positionAt ( x )

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

    See also TextInput::positionAt().


    TextField::positionToRectangle ( pos )

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

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

    See also cursorPosition and TextInput::positionToRectangle().


    TextField::select ( start, end )

    Selects the text from the position start to end. The start or end must be within the size of the text. Further start can be greater than or lesser than end. selectionStart will be set to the lesser of either start or end and similarly, selectionEnd will be set to the greater of either values.

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


    TextField::selectAll ()

    Selects all text in the text field.

    See also TextInput::selectAll().


    TextField::selectWord ()

    Selects the word closest to the current cursor position.

    See also TextInput::selectWord().