API Documentation

Documentation for developing SailfishOS applications

TextField QML Type

Displays a single line of editable plain text More...

Import Statement: import Sailfish.Silica 1.0
Inherited By:

PasswordField and SearchField

Properties

Signals

Methods

Detailed Description

The TextField type provides a display for a single line of editable plain text.

Here is a simple text field:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 TextField {
     focus: true
     text: "A single line of text"
 }

A text field can initially display some text that will automatically disappear once text is entered into the text field. This placeholder text is set through the placeholderText property:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 TextField {
     width: 480
     height: 300
     placeholderText: "Enter text here!"
 }

The label text is displayed below the input area when text is not empty, providing context for the text field. The convention typically used is:

 TextField {
     placeholderText: "Enter Username"
     label: "Username"
 }

A TextField item can only display plain text. To display rich formatted text, use TextArea instead.

Text input validation

A text field may disallow the entry of particular characters through the user of validators. For example, the RegExpValidator below ensures that only digits or characters from a specific set may be entered. Additionally, the user should enter a minimum of six characters. (While the field does not erase its text if a smaller number of characters are entered, it will set its errorHighlight property to true, and this may be used to indicate that the field is not vaild.)

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 TextField {
     width: 480
     placeholderText: "Enter phone number"
     validator: RegExpValidator { regExp: /^[0-9\+\-\#\*\ ]{6,}$/ }
     color: errorHighlight? "red" : Theme.primaryColor
     inputMethodHints: Qt.ImhNoPredictiveText
 }

Password-style entry, where entered characters should not be displayed, can be enabled by setting echoMode to TextInput.Password.

See also TextArea.

Property Documentation

[read-only] acceptableInput : bool

Indicates whether the validator accepts the current text value.

This is true if no validator has been set.

See also validator.


autoScrollEnabled : bool

Holds whether the text field will automatically scroll the Flickable that contains it to ensure visibility, when the text field gains active focus and when input is provided.

The default is true.


background : Component

The Component to use to draw the background of the text field.


color : color

The color of the text.


cursorPosition : int

The character position of the cursor within the text.

The value ranges from 0 to the number of characters in text.


echoMode : enumeration

Controls how entered text is displayed. This is one of:

  • TextInput.Normal - displays all text as entered (the default value)
  • TextInput.Password - displays asterisks in place of entered text
  • TextInput.PasswordEchoOnEdit - displays text as entered when the item has active focus and the text is being modified; otherwise, displays asterisks in place of entered text
  • TextInput.NoEcho - entered text is not displayed

errorHighlight : bool

True if the text field should be highlighted to indicate that the current text input is invalid.

This defaults to the inverse value of acceptableInput.


font.bold : bool

True if the displayed text is rendered in bold, otherwise false.


font.capitalization : enumeration

Holds the capitalization formatting that is applied to the displayed text. This is one of:

  • Font.MixedCase - no capitalization is applied (the default value)
  • Font.AllUppercase - all text is rendered in uppercase
  • Font.AllLowercase - all text is rendered in lowercase
  • Font.SmallCaps - text is rendered in small caps
  • Font.Capitalize - the first letter of each word is rendered with a capital letter

font.family : string

The name of the font family for rendering the displayed text.


font.italic : bool

True if the displayed text is rendered in italics, otherwise false.


font.letterSpacing : real

Controls the spacing (in pixels) between letters in the displayed text.

Specifying a positive value increases the default spacing between letters, and specifying a negative value decreases this spacing.


font.pixelSize : int

The size of the displayed text, in pixels.


font.pointSize : real

The size of the displayed text, in points.


font.strikeout : bool

True if the displayed text is rendered with a strikeout style, otherwise false.


font.underline : bool

True if the displayed text is rendered with an underline, otherwise false.


font.weight : enumeration

Holds the weight value for rendering the displayed text.

This is one of the following (listed from lightest to heaviest):

  • Font.Light
  • Font.Normal (the default value)
  • Font.DemiBold
  • Font.Bold
  • Font.Black

font.wordSpacing : real

Controls the spacing (in pixels) between words in the displayed text.

Specifying a positive value increases the default spacing between words, and specifying a negative value decreases this spacing.


horizontalAlignment : enumeration

The horizontal alignment of the text within the text field's width and height.

By default, the 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.

Valid values are:

  • TextInput.AlignLeft (default)
  • TextInput.AlignRight
  • TextInput.AlignHCenter
  • TextInput.AlignJustify

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 TextField, use the property LayoutMirroring::enabled.


inputMethodHints : Qt::InputMethodHints

Holds the hints to the input panel about the nature of the input this field expects. The input panel will display an input method suitable for the hints provided. The hints may be or'ed together:

 TextField {
     inputMethodHints: Qt.ImhEmailCharactersOnly | Qt.ImhNoPredictiveText
 }

The supported input method hints are:

  • Qt.ImhDialableCharactersOnly - Phone numbers
  • Qt.ImhDigitsOnly - Integer numbers
  • Qt.ImhEmailCharactersOnly - Email field
  • Qt.ImhFormattedNumbersOnly - Decimal numbers
  • Qt.ImhNoPredictiveText - Disable prediction
  • Qt.ImhUrlCharactersOnly - Web address
  • Qt.ImhNoAutoUppercase - Disable switch to uppercase at beginning of sentences

See also softwareInputPanelEnabled.


label : string

Text to display below the text entry field when text is not empty. This is useful for providing a description of the information to be entered in the text field. It is typically used in conjunction with placeholderText.

The default value is an empty string.

See also text, placeholderText, and labelVisible.


labelVisible : bool

Holds whether the label text will be displayed below the input field when text is not empty.

Setting to false hides the label and releases the space reserved for the label.

The default value is true.

See also label.


placeholderColor : string

The color of the placeholderText.

By default, the color is Theme.secondaryHighlightColor when the text field has active focus, and Theme.secondaryColor otherwise.

See also placeholderText.


placeholderText : string

The text to be displayed when text is empty. This is useful for providing an indication of the information to be entered in the text field. It is typically used in conjunction with label.

The default value is an empty string.

See also text, placeholderColor, and label.


readOnly : bool

Holds whether the text field is in read-only mode.

If set to true, the user cannot edit the text.


selectedText : string

The text that is currently selected.


selectionEnd : int

The position of the end of the selected text.

This is a readonly property. The user can modify the selection by double tapping the text and moving the handles. The selection can be set programatically via the select(), selectAll() or selectWord() functions.

See also select() and selectedText.


selectionMode : enumeration

Holds how text should be selected when dragging a selection handle. This is one of:

  • TextInput.SelectCharacters - The selection is updated character by character. (Default)
  • TextInput.SelectWords - The selection is updated word by word.

selectionStart : int

The position of the start of the selected text.

This is a readonly property. The user can modify the selection by double tapping the text and moving the handles. The selection can be set programmatically via the select(), selectAll() or selectWord() functions.

See also select() and selectedText.


softwareInputPanelEnabled : bool

Holds whether the on-screen key input panel is displayed when the text field gains active focus.

The default is true.


text : string

The displayed text.


textLeftMargin : real

The margin to the left of the displayed text, within the bounds of the text field.

Defaults to the value of textMargin.


textMargin : real

The margin to the left and the right of the displayed text, within the bounds of the text field.

This can be overriden by textLeftMargin and textRightMargin.


textRightMargin : real

The margin to the right of the displayed text, within the bounds of the text field.

Defaults to the value of textMargin.


[read-only] textVerticalCenterOffset : real

The vertical offset from top of the text field to the center of the actual editor element. This property can be used for centering e.g. an icon with the editor element:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 Page {
     TextField {
         id: textField
     }

     Image {
         anchors {
             left: textField.right
             verticalCenter: textField.top
             verticalCenterOffset: textField.textVerticalCenterOffset
         }
     }
 }

validator : Validator

The object that validates any entered text. By default, a text field does not have a validator.

A validator is used to filter entered text and prevent unacceptable text from being entered. For example, the IntValidator below ensures that the user may only enter numbers between 1-10 into the text field:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 TextField {
     width: 480
     placeholderText: "Enter phone number"
     validator: IntValidator { bottom: 1; top: 10 }
 }

Signal Documentation

onClicked(variant mouse)

This signal handler is called when the text field is clicked. The mouse parameter provides information about the click.


onPressAndHold(variant mouse)

This signal handler is called when there is a long press on the text field. The mouse parameter provides information about the press.


Method Documentation

copy()

Copies the currently selected text and places it in the clipboard.

See also select() and paste().


cut()

Removes the currently selected text and places it in the clipboard.

See also select() and paste().


deselect()

Removes the text selection. The text remains unchanged.

See also select().


forceActiveFocus()

Forces active focus on the text field.

When an item has Item::activeFocus, it becomes the item that receives keyboard input.


paste()

If there is a selection then the selection will be replaced with the contents of the clipboard; otherwise inserts the contents of the clipboard into the text at the cursorPosition.


int positionAt(x, y)

Returns the character position closest to the point at (x, y).


rect positionToRectangle(int position)

Returns a rectangle of the geometry where the cursor position would be if it was placed at the specified character position.


select(int start, int end)

Selects the text from start to end.

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

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

See also selectionStart, selectionEnd, and selectedText.


selectAll()

Selects all of the text.

See also select().


selectWord()

Selects the word nearest the cursorPosition.

See also select().


We use cookies to improve your user experience and to help us to develop our services. By continuing to browse the site, you approve of our use of cookies.