Qt Reference Documentation

QML TextField Element

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

This element was introduced in Qt Quick Components 1.0.

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.

TextField Basic Examples

The code examples below illustrate various features of TextField.

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

The examples below illustrate various TextField selection features in Symbian. Different options become available when the user selects a piece of text.

Selected TextAdjust Selection

Place CursorPaste Menu

Custom buttons to TextField

This section shows examples how to add a custom button and operations into a TextField component.

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

acceptableInput : 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 for the set validator or input mask.

Otherwise the value is false.

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


cursorPosition : int

The position of the cursor in a TextField.

See also TextInput::cursorPosition.


echoMode : int

Specifies how the text is displayed when the user enters text into the TextField. 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.


enabled : bool

If the value is true, the user can interact with the TextField; otherwise not.

The default value is true.

See also readOnly.


errorHighlight : bool

If the value is true, the TextField's graphics show that it contains invalid input; otherwise not. By default, this property responds to a validator you have set.

See the TextField Basic Examples section for an example.

See also TextInput::validator.


font : font

The text's font information in the TextField. The possible values are the same as those defined for TextInput.

See also TextInput.


inputMask : string

Allows you to restrict what the user can enter into the TextField. 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.


inputMethodHints : int

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

See also Qt::InputMethodHints.


maximumLength : 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 the value is 32767.

See also TextInput::maximumLength.


placeholderText : string

The placeholder text that is shown in the TextField to hint at the expected input. The placeholder text is shown in the text field as long as it has no focus and the user has not entered any text to the TextField. The default value of placeholderText is an empty string.

See the TextField Basic Examples section for an example.


platformInverted : bool

Symbian:

If platformInverted is true, the component is visualized with the inverted style. For more information, see Using Inverted Style with Symbian Components. By default platformInverted is false.

This property group was introduced in Qt Quick Components 1.1.


platformLeftMargin : real

Specifies the text's left margin in the TextField.


platformRightMargin : real

Specifies the text's right margin in the TextField.


readOnly : bool

If the value is true, the user can interact (select, copy, and scroll) with but not edit the TextField's text. If the value is false, the user can also edit the text.

See the TextField Basic Examples section for an example.

See also TextInput::readOnly and enabled.


selectedText : string

The currently selected text in the text field.

See also TextInput::selectedText.


selectionEnd : int

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

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


selectionStart : int

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

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


text : string

The text that has been entered into the text field.

See also placeholderText.


validator : 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::closeSoftwareInputPanel ()

Closes the virtual keyboard shown on the screen. On Symbian-based devices the user can open the virtual keyboard by tapping the TextField.

Note: Currently closeSoftwareInputPanel does not work on Symbian. For more information, see QTBUG-20033.

See also openSoftwareInputPanel and TextEdit::closeSoftwareInputPanel().


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::openSoftwareInputPanel ()

Opens the virtual keyboard for typing. On Symbian-based devices the user can open the virtual keyboard by tapping the TextField.

See also closeSoftwareInputPanel and TextEdit::openSoftwareInputPanel().


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 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 TextInput::positionToRectangle().


TextField::select ( start, end )

Selects the text from start to end.

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


TextField::selectAll ()

Selects all the text in the text field.

See also TextInput::selectAll().


TextField::selectWord ()

Selects the word closest to the current cursor position.

See also TextInput::selectWord().