ttk_entry

Виджет ttk::entry отображает строку текста одной строки и позволяет пользователю редактировать эту строку. Значение строки может быть связано с переменной Tcl с помощью -textvariable option. Entry widgets support horizontal scrolling with the standard -xscrollcommand option and xview widget command.

Стандартные параметры

-class, undefined, undefined
-cursor, cursor, Cursor
-style, style, Style
-takefocus, takeFocus, TakeFocus
-xscrollcommand, xScrollCommand, ScrollCommand

Параметры, специфичные для виджета

Имя в командной строке: -exportselection
Имя в базе данных: exportSelection
Класс в базе данных: ExportSelection: Булево значение, определяющее, должна ли выделенная область в виджете быть связана с выбором X. Если выделение экспортируется, то выделение в виджете отменяет текущий выбор X, выделение вне виджета отменяет любой выбор виджета, и виджет будет реагировать на запросы получения выделения, когда у него есть выделенная область.
Имя в командной строке: -invalidcommand
Имя в базе данных: invalidCommand
Класс в базе данных: InvalidCommand: Шаблон сценария, который оценивается всякий раз, когда -validatecommand возвращает 0. Дополнительную информацию см. в разделе ВАЛИДАЦИЯ ниже.
Имя в командной строке: -justify
Имя в базе данных: justify
Класс в базе данных: Justify: Определяет способ выравнивания текста внутри виджета ввода. Одно из значений left, center или right.
Имя в командной строке: -show
Имя в базе данных: show
Класс в базе данных: Show: Если этот параметр указан, то истинное содержимое поля ввода не отображается в окне. Вместо этого каждый символ в значении поля ввода отображается как первый символ в значении этого параметра, например, «*» или пуля. Это полезно, например, если поле ввода используется для ввода пароля. Если символы в поле ввода выбраны и скопированы в другое место, скопированная информация будет отображаться, а не истинное содержимое поля ввода.
Имя в командной строке: -state
Имя в базе данных: state
Класс в базе данных: State: Параметр совместимости; см. ttk::widget(n) для получения подробностей. Указывает одно из трех состояний поля ввода, normal, disabled или readonly. См. СОСТОЯНИЯ ВИДЖЕТОВ ниже.
Имя в командной строке: -textvariable
Имя в базе данных: textVariable
Класс в базе данных: Variable: Указывает имя глобальной переменной, значение которой связано с содержимым виджета ввода. Всякий раз, когда значение переменной изменяется, содержимое виджета обновляется, и наоборот.
Имя в командной строке: -validate
Имя в базе данных: validate
Класс в базе данных: Validate: Указывает режим работы проверки: none, focus, focusin, focusout, key или all. По умолчанию none, что означает отключение проверки. См. ВАЛИДАЦИЯ ниже.
Имя в командной строке: -validatecommand
Имя в базе данных: validateCommand
Класс в базе данных: ValidateCommand: Шаблон сценария, который оценивается всякий раз, когда запускается проверка. Если значение равно пустой строке (значение по умолчанию), проверка отключена. Сценарий должен возвращать булево значение. См. ВАЛИДАЦИЯ ниже.
Имя в командной строке: -width
Имя в базе данных: width
Класс в базе данных: Width: Указывает целое значение, определяющее желаемую ширину окна ввода, в символах среднего размера шрифта виджета.

Примечания

Часть поля ввода может быть выбрана, как описано ниже. Если поле ввода экспортирует свой выбор (см. параметр -exportselection), то оно будет наблюдать за стандартными протоколами X11 для обработки выбора; выборы полей ввода доступны как тип STRING. Поля ввода также соблюдают стандартные правила Tk для работы со вводом фокуса. Когда у поля ввода есть фокус ввода, оно отображает курсор вставки, чтобы указать, куда будут вставлены новые символы.

Поля ввода могут отображать строки, которые слишком длинные, чтобы полностью поместиться в окне виджета. В этом случае будет отображаться только часть строки; описанные ниже команды могут использоваться для изменения отображения в окне. Поля ввода используют стандартный механизм -xscrollcommand для взаимодействия со скроллбарами (см. описание параметра -xscrollcommand для получения подробностей).

Индексы

Многие команды виджета entry принимают один или несколько индексов в качестве аргументов. Индекс определяет конкретный символ в строке поля ввода одним из следующих способов:

число: Указывает символ как числовой индекс, где 0 соответствует первому символу в строке.
@число: В этой форме число обрабатывается как координата x в окне записи; используется символ, занимающий эту координату x. Например, «@0» указывает самый левый символ в окне.
end: Указывает символ, расположенный сразу после последнего символа в строке записи. Это эквивалентно указанию числового индекса, равного длине строки записи.
insert: Указывает символ, расположенный рядом и непосредственно после курсора вставки.
sel.first: Указывает первый символ в выделении. Использование этой формы является ошибкой, если выделение не находится в окне записи.
sel.last: Указывает символ, расположенный сразу после последнего символа в выделении. Использование этой формы является ошибкой, если выделение не находится в окне записи.

Для любого из вышеперечисленных форм могут использоваться аббревиатуры, например, «e» или «sel.l». В общем случае индексы, выходящие за пределы допустимого диапазона, автоматически округляются до ближайшего допустимого значения.

Команда виджета

Следующие подкоманды возможны для виджетов ввода:

pathName bbox index

Возвращает список из четырех чисел, описывающих рамку символа, заданного параметром index. Первые два элемента списка — координаты x и y верхнего левого угла области на экране, занимаемой символом (в пикселях относительно виджета), а последние два элемента — ширина и высота символа в пикселях. Рамка может относиться к области, находящейся за пределами видимой части окна.

pathName delete first ?last?

Удаляет один или несколько элементов из записи. First — индекс первого удаляемого символа, а last — индекс символа, идущего сразу после последнего удаляемого символа. Если last не указан, он по умолчанию равен first+1, то есть удаляется только один символ. Эта команда возвращает пустую строку.

pathName get

Возвращает строку записи.

pathName icursor index

Устанавливает курсор вставки перед символом, заданным параметром index. Возвращает пустую строку.

pathName index index

Возвращает числовой индекс, соответствующий index.

pathName insert index string

Вставляет string перед символом, указанным параметром index. Возвращает пустую строку.

pathName selection option arg

Эта команда используется для изменения выделения внутри поля ввода. Она имеет несколько форм в зависимости от option:

pathName selection clear: Очищает выделение, если оно присутствует в этом виджете. Если выделение не в этом виджете, команда не имеет эффекта. Возвращает пустую строку.
pathName selection present: Возвращает 1, если в поле ввода выделены символы, и 0, если ничего не выделено.
pathName selection range start end: Устанавливает выделение, включающее символы, начиная с символа с индексом start и заканчивая символом перед символом с индексом end. Если end ссылается на тот же символ, что и start, или на более ранний, выделение в поле ввода очищается.

pathName validate

Вызывает перепроверку, независимо от условий, заданных опцией -validate. Возвращает 0, если проверка не пройдена, и 1, если она пройдена. Соответственно устанавливает или сбрасывает состояние invalid. Дополнительные сведения см. в разделе ПРОВЕРКА ниже.

pathName xview args

Эта команда используется для запроса и изменения горизонтального положения текста в окне виджета. Она может принимать следующие формы:

pathName xview: Возвращает список, содержащий два элемента. Каждый элемент — действительная дробь от 0 до 1; вместе они описывают горизонтальный диапазон, который виден в окне. Например, если первый элемент равен 0,2, а второй — 0,6, то 20% текста поля ввода находится слева за пределами экрана, средние 40% видны в окне, а 40% текста находится справа за пределами экрана. Эти значения совпадают со значениями, передаваемыми полосам прокрутки через опцию -xscrollcommand.
pathName xview index: Изменяет представление в окне таким образом, что символ, заданный параметром index, отображается на левом краю окна.
pathName xview moveto fraction: Изменяет представление в окне таким образом, что символ, находящийся на расстоянии fraction от начала текста, отображается на левом краю окна. Fraction должна быть дробью от 0 до 1.
pathName xview scroll number what: Эта команда смещает представление в окне влево или вправо в соответствии со значениями number и what. Number должно быть целым числом. What должно быть либо units, либо pages. Если what равно units, представление смещается влево или вправо на number символов средней ширины на экране; если оно равно pages, представление смещается на number экранов. Если number отрицательное, то символы, находящиеся левее, становятся видимыми; если оно положительное, то символы, находящиеся правее, становятся видимыми.

Виджет поля ввода также поддерживает следующие общие подкоманды виджета ttk::widget (см. ttk::widget(n) для получения подробностей):

cget	configure	identify
instate	state

Проверка

Опции -validate, -validatecommand и -invalidcommand используются для включения проверки виджета поля ввода.

Режимы проверки

Существуют два основных режима проверки: prevalidation, в котором -validatecommand оценивается перед каждым изменением, а возвращаемое значение используется для определения того, принять или отклонить изменение; и revalidation, в котором -validatecommand оценивается для определения того, является ли текущее значение корректным.

Опция -validate определяет, когда происходит проверка; она может принимать следующие значения:

none: По умолчанию. Это означает, что валидация будет выполняться только при явном запросе команды виджета validate.
key: Запись будет предварительно валидирована перед каждым изменением (конкретно, каждый раз при вызове команд виджета insert или delete). Если предварительная валидация завершится неудачей, изменение отклоняется.
focus: Запись перевалидируется при получении или потере фокуса.
focusin: Запись перевалидируется при получении фокуса.
focusout: Запись перевалидируется при потере фокуса.
all: Валидация выполняется для всех вышеперечисленных условий.

Команда -invalidcommand оценивается всякий раз, когда команда -validatecommand возвращает значение ложь.

Команды -validatecommand и -invalidcommand могут изменять значение виджета ввода с помощью команд виджета insert или delete, или установив связанную переменную -textvariable. Если это происходит во время предварительной валидации, то изменение отклоняется независимо от значения, возвращенного командой -validatecommand.

Если -validatecommand пуста (по умолчанию), валидация всегда успешна.

Подстановки сценария валидации

Возможна замена процентов в командах -validatecommand и -invalidcommand, как и в скрипте bind. Распознаются следующие подстановки:

%d: Тип действия: 1 для предварительной валидации insert, 0 для предварительной валидации delete или -1 для перевалидации.
%i: Индекс строки символов, подлежащих вставке/удалению, если таковые имеются, в противном случае -1.
%P: При предварительной валидации — новое значение поля ввода, если изменение принимается. При перевалидации — текущее значение поля ввода.
%s: Текущее значение поля ввода до редактирования.
%S: Строка текста, вставляемая/удаляемая, если таковая имеется, в противном случае {}.
%v: Текущее значение опции -validate.
%V: Условие валидации, которое вызвало обратный вызов (key, focusin, focusout или forced).
%W: Имя виджета ввода.

Отличия от валидации виджета tk entry

Стандартный виджет Tk entry автоматически отключает валидацию (устанавливая -validate в none), если -validatecommand или -invalidcommand изменяют значение поля ввода. Виджет Tk themed entry отключает валидацию только если один из сценариев валидации вызывает ошибку или если -validatecommand не возвращает действительное булево значение. (Таким образом, нет необходимости повторно включать валидацию после изменения значения поля ввода в сценарии валидации).

Кроме того, стандартный виджет ввода вызывает валидацию всякий раз, когда изменяется связанная переменная -textvariable; виджет Tk themed entry этого не делает.

Связанные по умолчанию привязки

По умолчанию связанные привязки виджета ввода позволяют следующее поведение. В описаниях ниже, "слово" относится к непрерывной группе букв, цифр или символов "_", или к любому одиночному символу, отличного от этих.

Нажатие левой кнопки мыши помещает курсор вставки непосредственно перед символом под курсором мыши, устанавливает фокус ввода на этот виджет и очищает любой выделенный фрагмент текста в виджете. Перетаскивание с нажатой левой кнопкой мыши выделяет область между курсором вставки и символом под курсором.
Двойной щелчок левой кнопкой мыши выделяет слово под курсором и помещает курсор вставки в конец этого слова. Перетаскивание после двойного щелчка выделяет область, состоящую из целых слов.
Тройной щелчок левой кнопкой мыши выделяет весь текст в поле ввода и помещает курсор вставки в конец строки.
Границы выделенного фрагмента текста можно настроить, перетаскивая с нажатой левой кнопкой мыши и удерживая нажатой клавишу Shift. Если перед перетаскиванием нажать кнопку дважды, то выделение будет изменяться с шагом в целые слова.
Нажатие левой кнопки мыши при нажатой клавише Ctrl поместит курсор вставки в поле ввода, не затрагивая выделение.
Если в поле ввода вводятся любые стандартные печатные символы, они вставляются в точку курсора вставки.
Вид в поле ввода можно настроить, перетаскивая с нажатой средней кнопкой мыши. Если нажать среднюю кнопку мыши без перемещения мыши, то выделенный фрагмент текста будет скопирован в поле ввода в позицию курсора.
Если мышь перетаскивается за пределы поля ввода слева или справа, удерживая нажатой левую кнопку, поле ввода автоматически прокручивается, чтобы сделать больше текста видимым (если вне экрана есть дополнительный текст на стороне, с которой мышь покинула окно).
Клавиши влево и вправо перемещают курсор вставки на один символ влево или вправо соответственно; они также очищают любое выделение в поле ввода. Если клавиши влево или вправо нажимаются с удерживаемой клавишей Shift, то курсор перемещается, а выделение расширяется, чтобы включить новый символ. Клавиши Ctrl+влево и Ctrl+вправо перемещают курсор по словам, а клавиши Ctrl+Shift+влево и Ctrl+Shift+вправо перемещают курсор по словам и также расширяют выделение. Ctrl+b и Ctrl+f ведут себя так же, как клавиши влево и вправо соответственно.
Клавиша Home и Ctrl+a перемещают курсор вставки в начало поля ввода и очищают любое выделение. Клавиша Shift+Home перемещает курсор в начало поля ввода и расширяет выделение до этой точки.
Клавиша End и Ctrl+e перемещают курсор вставки в конец поля ввода и очищают любое выделение. Клавиша Shift+End перемещает курсор в конец и расширяет выделение до этой точки.
Ctrl+/ выделяет весь текст в поле ввода.
Ctrl-\ очищает любое выделение в поле ввода.
Стандартные виртуальные события Tk <<Вырезать>>, <<Копировать>>, <<Вставить>> и <<Очистить>> работают с выделенным фрагментом текста ожидаемым образом.
Клавиша Delete удаляет выделение, если оно есть в поле ввода. Если выделение отсутствует, она удаляет символ справа от курсора вставки.
Клавиша BackSpace и Ctrl+h удаляют выделение, если оно есть в поле ввода. Если выделение отсутствует, она удаляет символ слева от курсора вставки.
Ctrl+d удаляет символ справа от курсора вставки.
Ctrl+k удаляет все символы справа от курсора вставки.

Состояния виджета

В состоянии выключено поле ввода не может быть отредактировано, и текст не может быть выделен. В состоянии только для чтения не отображается курсор вставки, и поле ввода не может быть отредактировано (конкретно: команды вставка и удаление не имеют эффекта). Состояние выключено эквивалентно состоянию только для чтения, а кроме того текст не может быть выделен.

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

Как правило, текст в состоянии выключено «выглядит серым», а в состоянии только для чтения используется другой фон.

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

См. также

ttk::widget, entry

Licensed under Tcl/Tk terms
https://www.tcl.tk/man/tcl/TkCmd/ttk_entry.htm