QML-тип TextArea

Отображает несколько строк для редактирования простого текста. Подробнее...

Строка импорта: import Sailfish.Silica 1.0
Наследуется от: FocusScope

Свойства

Сигналы

Методы

Подробное описание

Тип TextArea реализует область для редактирования многострочного текста.

Ниже приведен пример текстовой области:

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

В общем случае ширину и высоту элемента TextArea следует указывать явно. В противном случае размеры текстовой области будут установлены так, чтобы вместить введенный текст text.

С помощью свойств font и color можно изменять параметры шрифта и цвет текста, соответственно. Выравнивание задается с помощью свойств horizontalAlignment и verticalAlignment, а перенос текста управляется свойством wrapMode.

В текстовой области изначально может отображаться текст заполнителя, который автоматически пропадет после начала ввода текста пользователем. Текст заполнителя задается с помощью свойства placeholderText:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

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

Текстовая метка label отображается под текстовой областью, если значение свойства text не пустое. Обычно используется следующее соглашение по наименованию данных элементов:

 TextArea {
     placeholderText: "Введите имя пользователя"
     label: "Имя пользователя"
 }

См. также TextField.

Описание свойств

autoScrollEnabled : bool

Определяет, будет ли текстовая область при получении фокуса и вводе текста автоматически прокручивать свой родительский элемент Flickable для обеспечения видимости содержимого.

Значение по умолчанию: true.

background : Component

Элемента типа Component, используемый для отрисовки фона текстовой области.

color : color

Цвет текста.

cursorPosition : int

Положение курсора в тексте.

Значение может лежать в диапазоне от 0 до числа символов в свойстве text.

font.bold : bool

При истинном значении текст отрисовывается полужирным.

font.capitalization : enumeration

Содержит стили форматирования, применяемые к регистру отображаемого текста. Данное свойство может принимать одно из значений:

  • Font.MixedCase - регистр текста не изменяется (значение по умолчанию);
  • Font.AllUppercase - весь текст отображается в верхнем регистре (прописными);
  • Font.AllLowercase - весь текст отображается в нижнем регистре (строчными);
  • Font.SmallCaps - текст отображается уменьшенными заглавными буквами (малыми прописными);
  • Font.Capitalize - первая буква в каждом слове отображается в верхнем регистре (прописными).

font.family : string

Название семейства шрифтов, которое используется для отображения текста.

font.italic : bool

При истинном значении текст отрисовывается курсивом.

font.letterSpacing : real

Межбуквенная разрядка (трекинг) в отображаемом тексте (в пикселях).

Указание положительных значений делает текст более разреженным, указание отрицательных значений уплотняет текст.

font.pixelSize : int

Размер отображаемого текста в пикселях.

font.pointSize : real

Размер отображаемого текста в пунктах.

font.strikeout : bool

При истинном значении текст отрисовывается зачеркнутым.

font.underline : bool

При истинном значении текст отрисовывается подчеркнутым.

font.weight : enumeration

Содержит значение веса, применяемое к отображаемом тексту.

Данное свойство может принимать одно из значений (от самого легкого к самому тяжелому):

  • Font.Light
  • Font.Normal (значение по умолчанию)
  • Font.DemiBold
  • Font.Bold
  • Font.Black

font.wordSpacing : real

Интервал между словами в отображаемом тексте (в пикселях).

Указание положительных значений увеличивает стандартный интервал между словами, указание отрицательных значений уменьшает его.

horizontalAlignment : enumeration

Выравнивание текста по горизонтали и по вертикали в пределах ширины и высоты текстовой области.

По умолчанию выравнивание текста соответствует направлению письма, принятого в языке. Например, если текст читается слева направо, то выравниваться он будет по левому краю.

Свойство horizontalAlignment может принимать следующие значения:

  • TextEdit.AlignLeft — выравнивание по левому краю (по умолчанию);
  • TextEdit.AlignRight — выравнивание по правому краю;
  • TextEdit.AlignHCenter — выравнивание по центру;
  • TextEdit.AlignJustify — выравнивание по ширине.

Свойство verticalAlignment может принимать следующие значения:

  • TextEdit.AlignTop — выравнивание по верхнему краю (по умолчанию);
  • TextEdit.AlignBottom — выравнивание по нижнему краю;
  • TextEdit.AlignVCenter — выравнивание по центру.

Если прикрепляемое свойство LayoutMirroring::enabled используется для зеркального отражения компоновки приложения, то это также влияет на горизонтальное выравнивание текста. При этом значение свойства horizontalAlignment останется неизменным. Узнать используемое на устройстве выравнивание по горизонтали для типа TextArea можно с помощью свойства LayoutMirroring::enabled.

inputMethodHints : Qt::InputMethodHints

Содержит настройки экранной клавиатуры, адаптирующие ее под тип вводимых данных. Экранная клавиатура меняет свой вид в зависимости от значения этого свойства. The hints may be OR'ed together:

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

Для экранной клавиатуры поддерживаются следующие методы ввода:

  • Qt.ImhDialableCharactersOnly — телефонные номера;
  • Qt.ImhDigitsOnly — целые числа;
  • Qt.ImhEmailCharactersOnly — поле ввода адреса электронной почты;
  • Qt.ImhFormattedNumbersOnly — дробные числа;
  • Qt.ImhNoPredictiveText — отключить предиктивный ввод текста;
  • Qt.ImhUrlCharactersOnly — символы, используемые для ввода URL;
  • Qt.ImhNoAutoUppercase — отключить автоматическое переключение в верхний регистр окончания ввода предложения.

См. также softwareInputPanelEnabled.

label : string

Текст метки, которая отображается под текстовой областью, если значение свойства text не пустое. Данный элемент полезно использовать для пояснения к информации, вводимой в текстовой области. Обычно используется в сочетании со свойством placeholderText.

Значение по умолчанию: пустая строка.

См. также text, placeholderText и labelVisible.

labelVisible : bool

Определяет, будет ли текстовая метка label отображаться под текстовой областью, если значение свойства text не пустое.

Установка значения в false скроет метку и освободит зарезервированное под нее пространство.

Значение по умолчанию: true.

См. также label.

placeholderColor : string

Цвет замещающего текста, задаваемого в свойстве placeholderText.

По умолчанию значение цвета равно Theme.secondaryHighlightColor, когда текстовая область находится в фокусе, и Theme.secondaryColor — в остальных случаях.

См. также placeholderText.

placeholderText : string

Замещающий текст, отображаемый при пустом значении свойства text. Данный элемент полезно использовать для обозначения информации, которую следует ввести в текстовой области. Обычно используется в сочетании со свойством label.

Значение по умолчанию: пустая строка.

См. также text и placeholderColor.

readOnly : bool

Определяет, можно ли изменять содержимое текстовой области.

При истинном значении пользователь не может редактировать текст.

selectedText : string

Выделенный в данный момент текст.

selectionEnd : int

Позиция конца выделенного текста.

Это свойство только для чтения. Пользователь может изменять выделение путем двойного касания текста и перемещения маркеров выделения текста. Выделение можно задать программно с помощью методов select(), selectAll() или selectWord().

См. также select() и selectedText.

selectionMode : enumeration

Определяет режим выделения текста путем перетаскивания с помощью соответствующих маркеров. Данное свойство может принимать одно из значений:

  • TextEdit.SelectCharacters — выделение осуществляется по отдельным символам (значение по умолчанию);
  • TextEdit.SelectWords — выделение осуществляется по словам.

selectionStart : int

Позиция начала выделенного текста.

Это свойство только для чтения. Пользователь может изменять выделение путем двойного касания текста и перемещения маркеров выделения текста. Выделение можно задать программно с помощью методов select(), selectAll() или selectWord().

См. также select() и selectedText.

softwareInputPanelEnabled : bool

Определяет, будет ли отображаться виртуальная клавиатура при получении фокуса текстовым полем.

Значение по умолчанию: true.

text : string

Отображаемый текст.

textLeftMargin : real

Отступ от левой границы отображаемого текста до границ текстовой области.

По умолчанию равно значению свойства textMargin.

textMargin : real

Отступ от левой и правой границ отображаемого текста до границ текстовой области.

textRightMargin : real

Отступ от правой границы отображаемого текста до границ текстовой области.

По умолчанию равно значению свойства textMargin.

[read-only] textVerticalCenterOffset : real

Смещение по вертикали от верхней границы текстовой области до центра первой строки текста в текстовой области. Данное свойство можно использовать для выравнивания других элементов, например, значков относительно области редактирования:

 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

Выравнивание текста по горизонтали и по вертикали в пределах ширины и высоты текстовой области.

По умолчанию выравнивание текста соответствует направлению письма, принятого в языке. Например, если текст читается слева направо, то выравниваться он будет по левому краю.

Свойство horizontalAlignment может принимать следующие значения:

  • TextEdit.AlignLeft — выравнивание по левому краю (по умолчанию);
  • TextEdit.AlignRight — выравнивание по правому краю;
  • TextEdit.AlignHCenter — выравнивание по центру;
  • TextEdit.AlignJustify — выравнивание по ширине.

Свойство verticalAlignment может принимать следующие значения:

  • TextEdit.AlignTop — выравнивание по верхнему краю (по умолчанию);
  • TextEdit.AlignBottom — выравнивание по нижнему краю;
  • TextEdit.AlignVCenter — выравнивание по центру.

Если прикрепляемое свойство LayoutMirroring::enabled используется для зеркального отражения компоновки приложения, то это также влияет на горизонтальное выравнивание текста. При этом значение свойства horizontalAlignment останется неизменным. Узнать используемое на устройстве выравнивание по горизонтали для типа TextArea можно с помощью свойства LayoutMirroring::enabled.

wrapMode : enumeration

Режим переноса текста при заполнении им ширины текстовой области. Текст будет переноситься только если для текстовой области явно задана ширина.

  • TextEdit.NoWrap — перенос текста не выполняется. Если в тексте недостаточно переносов строк для отображения текста, то значение унаследованного свойства implicitWidth будет больше заданной ширины текстовой области;
  • TextEdit.WordWrap — перенос выполняется только по границам слов. Если длина слова достаточно большая, то значение унаследованного свойства implicitWidth будет больше заданной ширины текстовой области;
  • TextEdit.WrapAnywhere — перенос выполняется в любом месте строки, даже если это происходит где-либо в пределах границ слова;
  • TextEdit.Wrap — по возможности, перенос выполняется по границам слова; если это невозможно, то перенос выполняется в подходящем месте строки, даже если это происходит где-либо в пределах границ слова.

Значение по умолчанию: TextEdit.NoWrap.

Описание сигналов

onClicked(variant mouse)

Обработчик данного сигнала вызывается при щелчке (касании) на текстовой области. Под щелчком в данном случае подразумевается нажатие и последующее отжатие текстовой области. Параметр mouse содержит в себе информацию о щелчке.

onPressAndHold(variant mouse)

Обработчик данного сигнала вызывается при нажатии и удерживании текстовой области. Параметр mouse содержит в себе информацию о нажатии.

Описание методов

copy()

Копирует выделенный текст в буфер обмена.

См. также select() и paste().

cut()

Удаляет выделенный текст и помещает его в буфер обмена.

См. также select() и paste().

deselect()

Снимает выделение с текста. Сам текст при этом не изменяется.

См. также select().

forceActiveFocus()

Принудительно устанавливает фокус на текстовой области.

При истинном значении унаследованного свойства Item::activeFocus элемент принимает ввод с виртуальной клавиатуры.

paste()

Если в текстовой области имеется выделенный текст, то он заменяется содержимым буфер обмена; в остальных случаях метод вставляет содержимое буфера обмена в текст в позицию курсора cursorPosition.

int positionAt(x, y)

Возвращает позицию символа, ближайшую к точке с координатами (x, y).

rect positionToRectangle(position)

Возвращает координаты и размеры прямоугольника курсора, расположенного в тексте в позиции position.

select(start,  end)

Выделяет текст от начального положения курсора start до конечного положения курсора end.

Если заданные начало и конец выделения находятся вне диапазона допустимых значений, то выделение не изменяется.

После вызова метода select(), значение свойства selectionStart станет меньше, а значение свойства selectionEnd станет большим (вне зависимости от порядка передачи аргументов в данный метод).

См. также selectionStart, selectionEnd и selectedText.

selectAll()

Выделяет весь текст.

См. также select().

selectWord()

Выделяет слово, ближайшее к положению курсора cursorPosition.

См. также select().