API Documentation

Documentation for developing SailfishOS applications

TextArea QML Type

Displays multiple lines of editable plain text More...

Import Statement: import Sailfish.Silica 1.0

Properties

Signals

Methods

Detailed Description

The TextArea type provides a display for multiple lines of editable plain text.

Here is a simple text area:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 TextArea {
     width: 480
     height: 300

     focus: true
     color: "orange"
     font.family: "cursive"

     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 consequat."
 }

The TextArea width and height should generally be set, otherwise the area will be sized to fit the entered text.

The displayed text can be formatted through the font and color properties. Text alignment is controlled through the horizontalAlignment and verticalAlignment properties, and text wrapping is controlled through the wrapMode property.

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

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 TextArea {
     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 area. The convention typically used is:

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

See also TextField.

Property Documentation

autoScrollEnabled : bool

Holds whether the text area will automatically scroll the Flickable that contains it to ensure visibility, when the text area 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 area.


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.


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 and vertical alignment of the text within the text area'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 for horizontalAlignment are:

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

Valid values for verticalAlignment are:

  • TextEdit.AlignTop (default)
  • TextEdit.AlignBottom
  • TextEdit.AlignVCenter

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 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:

 TextArea {
     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 area when text is not empty. This is useful for providing a description of the information to be entered in the text area. 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 area 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 area 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 area. It is typically used in conjunction with label.

The default value is an empty string.

See also text and placeholderColor.


readOnly : bool

Holds whether the text area 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:

  • TextEdit.SelectCharacters - The selection is updated character by character. (Default)
  • TextEdit.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 area 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 area.

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 area.


textRightMargin : real

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

Defaults to the value of textMargin.


[read-only] textVerticalCenterOffset : real

The vertical offset from top of the text area to the center of the first line 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 {
     TextArea {
         id: textArea
     }

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

verticalAlignment : enumeration

The horizontal and vertical alignment of the text within the text area'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 for horizontalAlignment are:

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

Valid values for verticalAlignment are:

  • TextEdit.AlignTop (default)
  • TextEdit.AlignBottom
  • TextEdit.AlignVCenter

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 property LayoutMirroring::enabled.


wrapMode : enumeration

Holds the mode used to wrap text to the width of the text area. The text will only wrap if an explicit width has been set.

  • TextEdit.NoWrap - no wrapping will be performed. If the text contains insufficient newlines, then implicitWidth will exceed a set width.
  • TextEdit.WordWrap - wrapping is done on word boundaries only. If a word is too long, implicitWidth will exceed a set width.
  • 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.

The default is TextEdit.NoWrap.


Signal Documentation

onClicked(variant mouse)

This signal handler is called when the text area 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 area. 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 area.

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(position)

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


select(start, 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.