listbox

Имя в командной строке: -activestyle
Имя базы данных: activeStyle
Класс базы данных: ActiveStyle: Устанавливает стиль отображения активного элемента. Допустимые значения: dotbox (отображает фокусную рамку вокруг активного элемента), none (без специального обозначения активного элемента) или underline (подчеркивает активный элемент). По умолчанию используется underline в Windows и dotbox в других системах.
Имя в командной строке: -height
Имя базы данных: height
Класс базы данных: Height: Устанавливает желаемую высоту окна в строках. Если значение равно нулю или меньше, высота окна устанавливается так, чтобы вместить все элементы в списке.
Имя в командной строке: -listvariable
Имя базы данных: listVariable
Класс базы данных: Variable: Устанавливает имя глобальной переменной. Значение переменной должно быть списком, который будет отображаться внутри виджета; если значение переменной изменяется, виджет автоматически обновляется для отражения нового значения. Попытка присвоить переменной некорректное значение списка в -listvariable вызовет ошибку. Попытка удалить переменную, используемую в -listvariable, завершится неудачей, но не вызовет ошибку.
Имя в командной строке: -selectmode
Имя базы данных: selectMode
Класс базы данных: SelectMode: Устанавливает один из нескольких стилей для управления выделением. Значение опции может быть произвольным, но стандартные привязки ожидают, что это будет single, browse, multiple или extended; значение по умолчанию — browse.
Имя в командной строке: -state
Имя базы данных: state
Класс базы данных: State: Устанавливает одно из двух состояний списка: normal или disabled. Если список отключен, то элементы нельзя вставлять или удалять, элементы отображаются в цвете -disabledforeground, выделение нельзя изменить и оно не отображается (хотя информация о выделении сохраняется).
Имя в командной строке: -width
Имя базы данных: width
Класс базы данных: Width: Устанавливает желаемую ширину окна в символах. Если шрифт не имеет одинаковой ширины, для перевода из символьных единиц в экранные используется ширина символа “0”. Если значение равно нулю или меньше, ширина окна устанавливается так, чтобы вместить все элементы в списке.

Описание

Команда listbox создаёт новое окно (указанное аргументом pathName) и преобразует его в виджет списка. Дополнительные опции, описанные выше, могут быть указаны в командной строке или в базе данных опций для настройки аспектов списка, таких как цвета, шрифт, текст и отступ. Команда listbox возвращает свой аргумент pathName. В момент вызова этой команды окно с именем pathName не должно существовать, но родительское окно pathName должно существовать.

Список — это виджет, который отображает список строк, по одной на строке. Когда он впервые создаётся, новый список не содержит элементов. Элементы можно добавлять или удалять с помощью команд виджетов, описанных ниже. Кроме того, можно выбрать один или несколько элементов, как описано ниже. Если список экспортирует своё выделение (см. опцию -exportselection), то он будет следовать стандартным протоколам X11 для обработки выделения. Выделения списка доступны как тип STRING; значение выделения будет текстом выбранных элементов, с разделителями из новых строк между элементами.

Не обязательно, чтобы все элементы отображались в окне списка сразу; команды, описанные ниже, могут использоваться для изменения представления в окне. Списка позволяют прокрутку в обоих направлениях с использованием стандартных опций -xscrollcommand и -yscrollcommand. Они также поддерживают поиск, как описано ниже.

Индексы

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

number: Определяет элемент как числовой индекс, где 0 соответствует первому элементу в списке.
active: Указывает элемент, на котором находится курсор. Этот элемент будет отображаться в соответствии с -activestyle, когда список имеет фокус клавиатуры, и он указан с помощью команды виджета activate.
anchor: Указывает точку якорной точки для выделения, которая устанавливается с помощью команды виджета selection anchor.
end: Указывает конец списка. Для большинства команд это относится к последнему элементу списка, но для некоторых команд, таких как index и insert, это относится к элементу, находящемуся сразу после последнего.
@x,y: Указывает элемент, который охватывает точку в окне списка, указанную x и y (в пиксельных координатах). Если ни один элемент не покрывает эту точку, используется ближайший к ней элемент.

В описаниях команд виджетов ниже, аргументы с именами index, first и last всегда содержат текстовые индексы в одном из указанных выше форматов.

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

Команда listbox создаёт новую команду Tcl, имя которой — pathName. Эта команда может быть использована для вызова различных операций над виджетом. Она имеет следующий общий вид:

pathName option ?arg arg ...?

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

pathName activate index

Устанавливает активным элемент, указанный index. Если index выходит за пределы диапазона элементов в списке, то активируется ближайший элемент. Активный элемент отображается в соответствии с параметром -activestyle, когда виджет имеет фокус, и его индекс можно получить с помощью active.

pathName bbox index

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

pathName cget option

Возвращает текущее значение параметра конфигурации, указанного option. Option может принимать любые значения, допустимые для команды listbox.

pathName configure ?option? ?value option value ...?

Запрос или изменение параметров конфигурации виджета. Если option не указан, возвращает список, описывающий все доступные параметры для pathName (см. Tk_ConfigureInfo для информации о формате этого списка). Если option указан без value, то команда возвращает список, описывающий указанный параметр (этот список будет идентичен соответствующему подсписку, возвращаемому, если option не указан). Если указана одна или несколько пар option-value, то команда изменяет указанный(ые) параметр(ы) виджета на указанное(ые) значение(я); в этом случае команда возвращает пустую строку. Option может принимать любые значения, допустимые для команды listbox.

pathName curselection

Возвращает список, содержащий числовые индексы всех элементов в списке, которые в настоящее время выбраны. Если в списке нет выбранных элементов, то возвращается пустая строка.

pathName delete first ?last?

Удаляет один или несколько элементов списка. First и last - индексы, определяющие первый и последний элементы в удаляемом диапазоне. Если last не указан, он по умолчанию равен first, т. е. удаляется только один элемент.

pathName get first ?last?

Если last опущено, возвращает содержимое элемента списка, указанного first, или пустую строку, если first ссылается на несуществующий элемент. Если last указан, команда возвращает список, элементы которого - все элементы списка между first и last включительно. first и last могут иметь любые стандартные формы индексов.

pathName index index

Возвращает целое значение индекса, соответствующее index. Если index равен end, значением возврата является количество элементов в списке (а не индекс последнего элемента).

pathName insert index ?element element ...?

Вставляет один или несколько новых элементов в список перед элементом с указанным index. Если index задан как end, то новые элементы добавляются в конец списка. Возвращает пустую строку.

pathName itemcget index option

Возвращает текущее значение параметра конфигурации элемента, указанного option. Option может принимать любые значения, допустимые командой itemconfigure.

pathName itemconfigure index ?option? ?value? ?option value ...?

Запрос или изменение параметров конфигурации элемента в списке. Если option не указан, возвращает список, описывающий все доступные параметры для элемента (см. Tk_ConfigureInfo для информации о формате этого списка). Если option указан без value, то команда возвращает список, описывающий указанный параметр (этот список будет идентичен соответствующему подсписку, возвращаемому, если option не указан). Если указана одна или несколько пар option-value, то команда изменяет указанный(ые) параметр(ы) элемента на указанное(ые) значение(я); в этом случае команда возвращает пустую строку. Следующие параметры в настоящее время поддерживаются для элементов:

-background color: Color задаёт цвет фона при отображении элемента. Он может принимать любые формы, допустимые для Tk_GetColor.
-foreground color: Color задаёт цвет текста при отображении элемента. Он может принимать любые формы, допустимые для Tk_GetColor.
-selectbackground color: color задаёт цвет фона при отображении выбранного элемента. Он может принимать любые формы, допустимые для Tk_GetColor.
-selectforeground color: color задаёт цвет текста при отображении выбранного элемента. Он может принимать любые формы, допустимые для Tk_GetColor.

pathName nearest y

При заданной координате y внутри окна списка, эта команда возвращает индекс элемента (видимого) списка, ближайшего к этой координате y.

pathName scan option args

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

pathName scan mark x y: Записывает x и y и текущий вид в окне списка; используется совместно с последующими командами scan dragto. Обычно эта команда связана с нажатием кнопки мыши на виджете. Возвращает пустую строку.
pathName scan dragto x y.: Эта команда вычисляет разницу между своими аргументами x и y и аргументами x и y последней команды scan mark для виджета. Затем она корректирует отображение, умножая разницу координат на 10. Эта команда обычно связана с событиями перемещения мыши в виджете, чтобы создать эффект быстрого протаскивания списка по окну. Возвращаемое значение - пустая строка.

pathName see index

Изменяет отображение в списке так, чтобы элемент с заданным index был виден. Если элемент уже виден, то команда не оказывает никакого влияния; если элемент находится близко к краю окна, то список прокручивается, чтобы привести элемент в вид на краю; в противном случае список прокручивается для центрирования элемента.

pathName selection option arg

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

pathName selection anchor index: Устанавливает якорную точку выделения на элемент с указанным index. Если index ссылается на несуществующий элемент, то используется ближайший элемент. Якорная точка выделения — это конец выделения, который фиксируется во время перетаскивания выделения мышкой. Индекс anchor может использоваться для ссылки на якорный элемент.
pathName selection clear first ?last?: Если любой из элементов между first и last (включительно) выделен, они отменяют выделение. Состояние выделения для элементов за пределами этого диапазона не изменяется.
pathName selection includes index: Возвращает 1, если элемент, указанный index, в настоящее время выбран, 0, если нет.
pathName selection set first ?last?: Выбирает все элементы в диапазоне между first и last, включительно, без изменения состояния выделения элементов за пределами этого диапазона.

pathName size

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

pathName xview ?args

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

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

pathName yview ?args?

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

pathName yview: Возвращает список, содержащий два элемента, оба из которых являются действительными дробями от 0 до 1. Первый элемент указывает положение элемента списка в верхней части окна относительно всего списка (0,5 означает, что он находится посередине списка, например). Второй элемент указывает положение элемента списка, расположенного сразу после последнего в окне, относительно всего списка. Эти значения идентичны значениям, передаваемым полосам прокрутки через параметр -yscrollcommand.
pathName yview index: Изменяет просмотр в окне таким образом, чтобы элемент, заданный параметром index, отображался вверху окна.
pathName yview moveto fraction: Изменяет просмотр в окне таким образом, чтобы элемент, заданный параметром fraction, отображался вверху окна. Fraction — дробь от 0 до 1; 0 указывает на первый элемент в списке, 0,33 — на элемент, находящийся на одной трети пути через список и так далее.
pathName yview scroll number what: Эта команда изменяет просмотр в окне вверх или вниз в соответствии с number и what. Number должен быть целым числом. What должно быть либо units, либо pages. Если what равно units, просмотр изменяется на number строк вверх или вниз; если оно равно pages, просмотр изменяется на number страниц. Если number отрицательно, то видимыми станут более ранние элементы; если положительно — более поздние.

Стандартные привязки

Tk автоматически создаёт привязки класса для списков, придавая им поведение, аналогичное Motif. Большое влияние на поведение списка оказывает его параметр -selectmode, который задаёт один из четырёх способов обработки выбора.

Если режим выбора равен single или browse, в списке одновременно может быть выбран не более одного элемента. В обоих режимах нажатие левой кнопки мыши на элемент выбирает его и отменяет выбор любого другого выделенного элемента. В режиме browse также можно перетаскивать выделение с помощью левой кнопки мыши. Нажатие левой кнопки мыши также переведёт фокус на список, если его состояние равно normal.

Если режим выбора равен multiple или extended, может быть выбрано любое количество элементов одновременно, включая несмежные диапазоны. В режиме multiple нажатие левой кнопки мыши на элемент переключает его состояние выбора, не влияя на другие элементы. В режиме extended нажатие левой кнопки мыши на элемент выбирает его, отменяет выбор всего остального и устанавливает якорь на элемент под курсором; перетаскивание мышью с нажатой левой кнопкой мыши расширяет выбор, включив все элементы между якорем и элементом под курсором включительно.

Большинство пользователей, вероятно, захотят использовать режим browse для одиночного выбора и extended для множественного; другие режимы, по-видимому, полезны только в особых ситуациях.

Всякий раз, когда набор выбранных элементов в списке обновляется пользователем с помощью клавиатуры или мыши, генерируется виртуальное событие <<ListboxSelect>>. Это виртуальное событие не генерируется при изменении выбора с помощью команды pathName selection. Легче всего привязаться к этому событию, чтобы быть в курсе любых изменений выбора в списке пользователем.

Помимо вышеперечисленного поведения, определено следующее дополнительное поведение:

В режиме extended диапазон выбора может быть изменён нажатием левой кнопки мыши с зажатой клавишей Shift: это меняет выбор таким образом, чтобы он состоял из элементов между якорем и элементом под курсором включительно. Непривязанный конец этого нового выбора также можно перетаскивать, удерживая кнопку мыши нажатой.
В режиме extended нажатие левой кнопки мыши с зажатой клавишей Ctrl запускает операцию переключения: якорь устанавливается на элемент под курсором, а его состояние выбора инвертируется. Состояние выбора других элементов не изменяется. Если перетаскивать мышь с нажатой левой кнопкой, состояние выбора всех элементов между якорем и элементом под курсором устанавливается в соответствии с состоянием якоря; состояние выбора всех других элементов остаётся тем, что было до начала операции переключения.
Если курсор мыши покидает окно списка с нажатой левой кнопкой, окно прокручивается от курсора мыши, делая видимой информацию, которая раньше была вне экрана с той стороны курсора мыши. Прокрутка продолжается до тех пор, пока курсор мыши не вернётся в окно, кнопка не будет отпущена или не будет достигнут конец списка.
Кнопка мыши 2 может использоваться для сканирования. Если её нажать и перетаскивать по списку, содержимое списка перемещается с высокой скоростью в направлении движения мыши.
При нажатии клавиш со стрелками вверх или вниз курсор (активный элемент) перемещается на один элемент вверх или вниз. Если режим выбора равен browse или extended, новый активный элемент также выбирается, и все остальные элементы отменяются. В режиме extended новый активный элемент становится якорем выбора.
В режиме extended клавиши Shift-Up и Shift-Down перемещают курсор (активный элемент) вверх или вниз на один элемент и также расширяют выбор до этого элемента аналогично перетаскиванию левой кнопкой мыши.
Клавиши влево и вправо прокручивают просмотр списка влево и вправо на ширину символа 0. Клавиши Ctrl-влево и Ctrl-вправо прокручивают просмотр списка влево и вправо на ширину окна. Клавиши Ctrl-PageUp и Ctrl-PageDown также прокручивают влево и вправо на ширину окна.
Клавиши PageUp и PageDown прокручивают просмотр списка вверх и вниз на одну страницу (высоту окна).
Клавиши Home и End прокручивают просмотр списка горизонтально до левого и правого краёв соответственно.
Ctrl-Home устанавливает курсор на первый элемент в списке, выбирает этот элемент и отменяет выбор всех остальных элементов в списке.
Ctrl-End устанавливает курсор на последний элемент в списке, выбирает этот элемент и отменяет выбор всех остальных элементов в списке.
В режиме extended Ctrl-Shift-Home расширяет выбор до первого элемента в списке, а Ctrl-Shift-End — до последнего.
В режиме multiple Ctrl-Shift-Home перемещает курсор на первый элемент в списке, а Ctrl-Shift-End — на последний.
Пробел и клавиша выбора делают выбор в позиции курсора (активного элемента), точно так же, как если бы левая кнопка мыши была нажата над этим элементом.
В режиме extended Ctrl-Shift-пробел и Shift-выбор расширяют выбор до активного элемента, точно так же, как если бы левая кнопка была нажата с зажатой клавишей Shift.
В режиме extended клавиша Esc отменяет последний выбор и восстанавливает все элементы в выделенном диапазоне в их предыдущее состояние выбора.
Ctrl-сlashes выбирает всё в виджете, за исключением режимов single и browse, в которых он выбирает активный элемент и отменяет выбор всего остального.
Ctrl-backslash отменяет выбор всего в виджете, за исключением режима browse, где он не оказывает никакого влияния.
Кнопка F16 (на многих рабочих станциях Sun обозначена как Копировать) или Meta-w копирует выделение в виджете в буфер обмена, если выделение существует.

Поведение списков можно изменить, определив новые привязки для отдельных виджетов или переопределив привязки класса.

См. также

ttk::treeview

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