listbox

Команда создает и управляет примитивами окон со списками.

СИНТАКСИС

      listbox имяПути ?параметры?

СТАНДАРТНЫЕ ПАРАМЕТРЫ

Подробное описание этих параметров приведено в разделе options.

ДОПОЛНИТЕЛЬНЫЕ ПАРАМЕТРЫ ПРИМИТИВА

Имя параметра:-height
Имя в Базе:height
Класс в Базе:Height

Задает желаемую высоту окна (число строчек текста в нем). Если значение параметра неположительно, то высота окна выбирается таким образом, чтобы в нем помещались все элементы списка.

Имя параметра:-selectmode
Имя в Базе:selectMode
Класс в Базе:SelectMode

Задает один из нескольких стилей управления выделением. Параметр может принимать произвольное значение, однако привязки по умолчанию предполагают, что его значение является одним из следующих: single, browse, multiple или listbox. По умолчанию параметр имеет значение browse.

Имя параметра:-width
Имя в Базе:width
Класс в Базе:Width

Задает желаемую ширину окна (число символов в строчке текста в нем). Если ширина символа в данном шрифте непостоянна, то для перевода числа символов в единицы экрана используется ширина символа "0". Если значение параметра неположительно, то ширина окна выбирается таким образом, чтобы в нем помещались все элементы списка.

ОПИСАНИЕ

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

Окно со списком представляет собой примитив, в котором выводятся строки элементы списка по одному на строчку окна. С помощью описываемых ниже команд примитива в список можно добавлять новые элементы или удалять элементы оттуда. Кроме того, можно выделить один или несколько элементов, как описано ниже. Экспорт выделенного текста (см. описание параметра exportSelection) осуществляется по стандартному протоколу X11 для выделений; выделения в поле ввода имеют тип STRING. Значение строки выделения составляется из выделенных элементов, разделенных символами перехода на новую строчку.

Все элементы списка не обязательно выводятся в окне со списком одновременно. Содержимое окна можно поменять с помощью описываемых ниже команд. Окна со списком поддерживают прокрутку в обоих направлениях с помощью стандартных параметров xScrollCommand и yScrollCommand. Кроме того, возможно сканирование окон (см. описание ниже).

ИНДЕКСЫ

Аргументами многих команд примитива окна со списком служат индексы. Индекс задает положение конкретного элемента в окне со списком. Он может иметь один из следующих видов:

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

Аргументы с именами индекс, первый и последний в описываемых ниже командах примитива представляют собой индексы в одной из описанных выше форм.

КОМАНДА ПРИМИТИВА

Команда listbox создает новую команду Tcl с именем имяПути. С помощью этой команды можно выполнять различные операции над примитивом. Ее общий вид

      имяПути параметр ?арг арг ...?

Параметр и аргументы уточняют поведение команды. Примитивы окна со списком допускает следующие формы команды:

имяПути activate индекс
Делает активным элемент, указанный аргументом индекс. Если значение аргумента индекс выходит за пределы списка, то активным становится элемент, ближайший к указанному. Если окно со списком находится в фокусе ввода, то активный элемент в нем выделен подчеркиванием, а доступ к нему осуществляется через индекс active.
имяПути bbox индекс
Возвращает список из четырех элементов, описывающий клетку, занимаемую текстом в элементе, указанном параметром индекс. Первые два элемента списка задают x- и y-координаты верхнего левого угла клетки (в пикселях по отношению к примитиву), последние два элемента ширину и высоту области (в пикселях). Если на экране не видна никакая часть элемента или если индекс указывает на несуществующий элемент, то команда возвращает пустую строку. Если же на экране видна хотя бы часть элемента, то результатом выполнения команды служит описание всей области, занимаемой элементом (в том числе и его невидимой частью).
имяПути cget параметр
Возвращает текущее значение параметра конфигурации с именем параметр. Параметр может быть любым из параметров команды listbox.
имяПути configure ?параметр? ?значение параметр значение ...?
Запрашивает значения параметров конфигурации примитива или изменяет их. Если параметр не указан, то возвращает список, содержащий значения всех допустимых в имениПути параметров (формат списка описан в Tk_ConfigureInfo). Если параметр задан, а его новое значение нет, то команда возвращает часть полного списка, относящуюся к указанному параметру. Если заданы одна или несколько пар параметр-значение, то указанным параметрам примитива присваиваются новые значения. В этом случае команда возвращает пустую строку. Параметр может быть любым из параметров команды listbox.
имяПути curselection
Возвращает список, состоящий из числовых значений индекса всех выделенных элементов. Если ни один из элементов не выделен, то возвращает пустую строку.
имяПути delete первый ?последний?
Удаляет один или несколько элементов списка. Аргумент первый является индексом первого, а аргумент последний индексом последнего удаляемого элемента. По умолчанию значение аргумента последний совпадает со значением аргумента первый, т.е. удаляется один элемент.
имяПути get первый ?последний?
Если аргумент последний не задан, то возвращает содержимое элемента списка, заданного аргументом первый (или пустую строку, если первый указывает на несуществующий элемент). Если аргумент последний задан, то команда возвращает список, элементами которого являются все элементы окна между первым и последним (включая оба эти элемента). Значением каждого из аргументов первый и последний может быть любое допустимое значение индекса.
имяПути index индекс
Команда возвращает числовое значение индекса, заданного аргументом индекс. Если аргумент индекс имеет значение end, то возвращаемое значение равно числу элементов в списке (а не индексу последнего элемента).
имяПути insert индекс ?элемент элемент ...
Вставляет элементы непосредственно перед элементом, на который указывает аргумент индекс. Если аргумент индекс имеет значение end, то новые элементы вставляются в конец списка. Команда возвращает пустую строку.
имяПути nearest y
По заданному значению y-координаты в окне со списком возвращает индекс ближайшего к этому значению (видимого) элемента списка.
имяПути scan параметр аргументы

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

имяПути scan mark x y
Запоминает значение координаты x и текущее состояние окна со списком; используется в сочетании с последующими командами scan dragto. Обычно эта команда связана с нажатием клавиши "Мыши" на примитиве. Возвращает пустую строку.
имяПути scan dragto x y
Вычисляет разность между значением своих аргумента x и y и значениями аргументов x и y последней выполненной на данном примитиве команды scan mark. Затем переносит изображение примитива на расстояние, в 10 раз превышающее вычисленную разность. Команда обычно связана с событиями движения "Мыши" в примитиве и используется для скоростного перетаскивания списка в окне. Возвращает пустую строку.
имяПути see индекс
Выравнивает список в окне так, чтобы элемент с индексом индекс оказался видимым. Если этот элемент уже является видимым, то команда не производит никаких действий. Если указанный элемент находится возле края окна, то при прокрутке списка элемент оказывается возле того же края; в противном случае указанный элемент выводится в центре окна.
имяПути selection параметр аргумент

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

имяПути selection anchor индекс
Устанавливает опорную точку выделения на элемент, указанный аргументом индекс. Если индекс указывает на несуществующий элемент, то опорным становится элемент, ближайший к указанному. Опорная точка выделения является фиксированным концом выделения при движении "Мыши" с нажатой клавишей. На опорную точку выделения указывает индекс anchor.
имяПути selection clear первый ?последний?
Отменяет выделение элементов между первым и последним. Вне этого интервала выделение не изменяется.
имяПути selection includes индекс
Возвращает "1", если элемент, указанный аргументом индекс, выделен, и "0" в противном случае.
имяПути selection set первый ?последний?
Выделяет все элементы в промежутке между первым и последним; на выделение вне указанного интервала команда влияния не оказывает.
имяПути xview аргументы

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

имяПути xview
Возвращает список, состоящий из двух элементов. Каждый из элементов списка представляет собой вещественное число, заключенное между нулем и единицей; эта пара чисел описывает видимый в окне горизонтальный интервал. Так, например, если первое число равно "2", а второе "6", то 20% текста в окне со списком оказывается невидимой слева от окна, в окне выводится 40% информации, и еще 40% оказывается невидимой справа от окна. Те же значения передаются полосе прокрутки через параметр -xscrollcommand.
имяПути xview индекс
Переносит строку в поле ввода так, что самым левым символом в окне становится символ, положение которого указано аргументом индекс. Положения символов определяются исходя из ширины символа 0.
имяПути xview moveto число
Передвигает область видимости так, что слева от окна остается невидимой часть текста списка, указанная аргументом число. Число должно быть заключено между "0" и "1".
имяПути xview scroll количество что
Сдвигает выводимый в окне текст вправо или влево в соответствии со значениями аргументов. Количество должно быть целым числом, аргумент что может принимать значения units или pages или быть сокращением одного из этих слов. Если аргумент что принимает значение units, то сдвиг происходит на количество символов средней ширины (ширины символов 0). Если значением аргумента что является pages, то сдвиг осуществляется на количество полных экранов. Если количество отрицательно, то видимые символы сдвигаются вправо, в противном случае влево.
имяПути yview аргументы

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

имяПути yview
Возвращает список, состоящий из двух элементов. Каждый из элементов списка представляет собой вещественное число, заключенное между нулем и единицей. Первый элемент списка задает положение в списке первого видимого в окне элемента (например, значение "0.5" указывает на середину списка). Второй элемент указывает положение в списке элемента, следующего непосредственно за последним видимым в окне. Те же значения передаются полосе прокрутки через параметр -xscrollcommand.
имяПути yview индекс
Переносит содержимое окна со списком таким образом, чтобы элемент, заданный аргументом индекс, оказался в первой строчке окна.
имяПути yview moveto число
Переносит содержимое окна со списком таким образом, чтобы элемент, заданный аргументом число, оказался в первой строчке окна. Число должно быть заключено между 0 и 1. 0 указывает на первый элемент в списке, 0.33 указывает на элемент, отстоящий от начала списка на одну треть, и т.д.
имяПути yview scroll количество что
Сдвигает выводимый в окне текст вверх или вниз в соответствии со значениями аргументов. Количество должно быть целым числом, аргумент что может принимать значения units или pages или быть сокращением одного из этих слов. Если аргумент что принимает значение units, то сдвиг происходит на количество строчек. Если значением аргумента что является pages, то сдвиг осуществляется на количество полных экранов. Если количество отрицательно, то видимые символы сдвигаются вниз, в противном случае вверх.

ПАРАМЕТРЫ ПО УМОЛЧАНИЮ

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

В режиме выделения single или browse допустимо выделение не более одного элемента. В обоих режимах щелчок клавишей 1 "Мыши" на элементе приводит к его выделению и отмене всех остальных выделений. В режиме browse выделенный элемент можно также перетащить с помощью клавиши 1 "Мыши".

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

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

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

В режиме extended выделенную область можно изменить нажатием клавиши 1 при нажатой клавише Shift; при этом выделенной становится вся область между опорной точкой и элементом под курсором "Мыши".

В режиме extended нажатие клавиши 1 при нажатой клавише Control начинает выполнение операции переключения: опорная точка устанавливается на элемент под курсором "Мыши", а состояние его выделения меняется на противоположное. Выделение остальных элементов не изменяется. Если тащить "Мышь" с нажатой клавишей 1, то состояние выделения всех элементов между опорной точкой и курсором "Мыши" меняется на состояние выделения опорного элемента; выделение остальных элементов не изменяется.

Если "Мышь" сдвигается с окна со списком при нажатой клавише 1, то информация в окне прокручивается в противоположном направлении. Прокрутка продолжается до тех пор, пока либо "Мышь" не вернется в область окна, либо будет достигнут конец списка.

Для прокрутки можно использовать клавишу 2 "Мыши". Если ее нажать и протащить "Мышь" по списку, то содержимое списка будет прокручиваться в направлении движения "Мыши".

При нажатии на клавиши Up или Down курсор окна (активный элемент) передвигается на одну строчку вверх или вниз. В режиме browse или extended новый активный элемент оказывается выделенным, а выделение всех остальных элементов отменяется. В режиме extended новый активный элемент становится опорной точкой выделения.

В режиме extended клавиши Shift-Up и Shift-Down передвигают курсор окна на одну строчку вверх или вниз и расширяют область выделения новым активным элементом подобно тому, как это делает клавиша 1 "Мыши".

Нажатие на клавиши Left или Right приводит к перемещению курсора ввода на ширину символа 0 влево или вправо.

Нажатие на клавиши Control-Left и Control-Right приводит к прокрутке списка на ширину окна, также, как и нажатие на клавиши Control-Prior и Control-Next.

Нажатие на клавиши Prior и Next приводит к прокрутке списка на одну страницу (на высоту окна) вверх или вниз.

Нажатие на клавиши Home и End прокручивает список горизонтально до его левого или правого края соответственно.

Нажатие на клавиши Control-Home устанавливает курсор окна на первый элемент списка, выделяет этот элемент и отменяет выделение всех остальных элементов.

Нажатие на клавиши Control-End устанавливает курсор окна на последний элемент списка, выделяет этот элемент и отменяет выделение всех остальных элементов.

В режиме extended нажатие на клавиши Control-Shift-Home расширяет выделение до первого элемента в списке, а на клавиши Control-Shift-End до последнего элемента в списке.

В режиме multiple нажатие на клавиши Control-Shift-Home устанавливает курсор окна на первый элемента в списке, а на клавиши Control-Shift-End на последний элемент в списке.

Клавиши пробела и Select выделяют активный элемент (курсор окна), как если бы на этом элементе была нажата клавиша1 "Мыши".

В режиме extended нажатие на клавиши Control-Shift-пробел и Shift-Select расширяет выделение до активного элемента, как если бы на этом элементе была нажата клавиша 1 "Мыши" при нажатой клавише Shift.

В режиме extended нажатие на клавиши Escape отменяет самое последнее выделение и восстанавливает предыдущее состояние выделение всех элементов в области выделения.

Control-/ выделяет все элементы окна.

Control-\ приводит к отмене текущего выделения (за исключением режима browse, где эта команда не приводит ни к какому результату).

Клавиша F16, на многих станциях Sun обозначенная Copy, (или Meta-w) копирует выделение в примитиве в карман.

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