Alterator/Widgets

В интерфейсе Lookout доступны следующие виджеты

Таблица виджетов (по состоянию на 20/08/2008)

(interfaces/guile/lookout/evaluation.scm)

Виджет	атрибут по умолчанию
radio	text
button	text
label	text
edit	text
groupbox	title
textbox	text
tab-page	text
checkbox	text
box
spinbox
gridbox
tabbox
listbox
checklistbox		устаревшее название -- checklist
combobox
progressbar
slider
tree
menubar
spacer
separator
dateedit
timeedit
splitbox

Основные виджеты

атрибуты всех виджетов

Следующие атрибуты есть у всех виджетов в дополнение к указанным ниже:

• visibility -- видимость/невидимость виджета
• activity -- активность/неактивность виджета
• widget-name -- символическое имя виджета
• tooltip -- справочная информация, выводимая в "пузыре" при наведении на данный виджет
• colspan -- указание сколько колонок данный виджет займёт внутри "сетки"
• rowspan -- указание сколько строк данный виджет займёт внутри "сетки"
• align -- указание выровнять данный виджет по краям ("left" - левый край, "right" - правый край) или по центру ("center") внутри ячейки "сетки"
• focus -- атрибут только для записи, помещает фокус на виджет для которого указано значение #t

корневой виджет

Именно в этот виджет вставляются все остальные, виджет является или vbox или dialog. У диалога, помимо атрибутов vbox, имеются следующие:

• title -- заголовок окна
• width -- ширина окна
• height -- высота окна

gridbox

"Сетка", основной способ организации виджетов на экране.

Атрибуты:

• columns -- перечисление того сколько процентов от общей ширины виджета будет занимать каждая колонка.

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

Пример:

(gridbox 
   columns "50;50" ; две колонки одинакового размера
  ;;первая строка
  (widget1)
  (widget2)
  ;;вторая строка, автоматически учитывается colspan
  (widget3 colspan 2)
  ;;третья строка
  (widget4)
  (widget5))

spacer

"Пустышка", применяется при заполнении пустых ячеек в таблице

separator

"Горизонтальная черта".

label

Метка, содержит или текст, или картинку. В зависимости от возможностей браузера могут выводиться или только один из этих двух вариантов, или оба одновременно.

Атрибуты:

• text -- текст
• pixmap -- картинка
• text-wrap -- переносить ли слишком длинные строки (#t/#f)

button

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

Aтрибуты:

• text -- текст
• pixmap -- картинка

События:

• clicked -- вызывается при нажатии кнопки.

radio

Радио-кнопка.

Атрибуты:

• text -- комментарий к кнопке
• state -- состояние (активна/неактивна)

События:

• toggled -- вызывается при изменении состояния кнопки.

checkbox

Кнопка с двумя состояниями.

Атрибуты:

• text -- комментарий к кнопке
• state -- состояние (выделен checkbox или нет, #t/#f).

События:

• toggled -- вызывается при изменении состояния кнопки.

edit

Однострочное текстовое поле.

Атрибуты:

• text -- содержимое
• echo -- режим отображения. Возможные варианты normal (по умолчанию), stars (звёздочки, для паролей), no (ввод не отображается).
• alterability -- возможности по изменению текста. Если значение #f, содержимое поля доступно только для чтения.

События:

• changed -- вызывается при изменении содержимого поля
• return-pressed -- вызывается при нажатии в поле клавиши Enter.

textbox

Многострочное текстовое поле. В Qt textbox способен отображать как plain text, так и html. При этом тип отображения определяется при первом задании атрибута text. Если первоначально был plain text, то при попытке записать в содержимое текст в формате html, последний будет отображаться как plain text.

Атрибуты:

• text -- содержимое
• append-text -- добавить указанную строку к содержимому.
• url -- показать содержимое указанного файла в textbox.
• alterability -- аналогично edit, если значение #f, то содержимое поля доступно только для чтения.

События:

• changed -- вызывается при изменении содержимого поля.

groupbox

Объединение группы виджетов.

Атрибуты:

• checked -- в случае значения #t рядом с заголовком отображается checkbox (если он не выделен, то содержимое группы неактивно и недоступно для работы).
• state -- состояние checkbox в случае режима checked.
• title -- заголовок группы

События:

• toggled -- вызывается в случае изменения состояния checkbox.

progressbar

Строка прогресса некоторого процесса.

Атрибуты:

• value -- текущее значение
• maximum -- максимальное значение

listbox

Многоколоночный список.

Атрибуты:

• columns -- количество колонок, по умолчанию 1.
• header -- заголовок таблицы, вектор из строк с названиями колонок. Если длина вектора меньше количества колонок -- оставшиеся колонки заполняются пробелами.
• rows -- список значений. Если список многоколоночный, то значения в одной строке объединяются внутри вектора, каждое поле -- строка или пара строка + картинка. Если в векторе-строке значений меньше, чем требуется, оставшиеся колонки заполняются пробелами.
• append-row -- добавить в конец списка новую строчку. Если список многоколоночный, то передаётся целый вектор значений, если нет, то достаточно передать просто строку или пару строка + картинка.
• remove -- удалить указанную строчку. Строчка указывается своим порядковым номером. В случае значения 'all - удаляются все строки.
• current -- номер выделенной строки. Если таковых не имеется, то значение равно -1.
• row-item -- работа с отдельным полем в списке. Координаты задаются списком из двух значений (строка колонка) или просто номером строки. Возвращает пару строка+картинка. При модификации поля указывается или просто строка или строка + картинка, если во втором случае одно из значений пары #f, то оно остаётся прежним.
• count -- возвращает количество строк в таблице.
• text -- возращает строку с содержимым первого поля активной строки.

События:

• selected -- вызывается при изменении активного элемента списка
• clicked -- вызывается при щелчке мышкой по элементу списка
• double-clicked -- вызывается при двойном щелчке по элементу списка.

Замечание: щёлкания могут перекрывать друг друга в случае HTML-интерфейса, поэтому лучше использовать что-то одно.

combobox

Выпадающий список.

Атрибуты: Все атрибуты listbox в одноколоночном режиме, а также:

• alterability -- значение #t переключает в редактируемый режим.

События:

• selected -- вызывается при изменении активного элемента

tree

Древообразный список элементов. Возможна многоколоночность в определённых браузерах.

Атрибуты:

• columns -- количество колонок, по умолчанию 1.
• tree-items -- элементы дерева, организованные в виде вложенных списков. Элементы на одной строке объединяются вектором, каждое поле или строка или строка+картинка. Поддерево вставляется под элемент следующий перед списком.
• current -- путь к активному элементу списка.
• tree-text -- список из строк первых колонок для каждого элемента пути к активному элементу.

События:

• selected -- вызывается в случае изменения активного элемента в дереве.

Стандартные диалоги

Для оповещения пользователей alterator предоставляет набор стандартных диалогов, общий формат вызова следующий:

(popup-имя сообщение кнопка1 кнопка2 ...)

первый параметр - сообщение, далее следует перечисление кнопок которые желаете видеть в диалоге. Кнопки задаются символами и могут быть одними из следующих: ok, open, save, cancel, close, discard, apply, reset, restore-defaults, help, save-all, yes, yes-to-all, no, no-to-all, abort, retry, ignore (также имеется специальное имя no-button - означает отсутствие кнопки). Результат исполнения диалога - символ, соответствующий нажатой кнопке. Доступны следующие виды диалогов:

• document:popup-information
• document:popup-warning
• document:popup-critical
• document:popup-question

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

Примеры:

(document:popup-critical "Большая проблема" 'ok)

(if (eq? 'yes (document:popup-question "Согласны?"  'no 'yes')) ; по умолчанию "нет".
    <действие при согласии>
    <дейтсвие при не согласии>)

Выше перечисленные функции на самом деле являются обёртками вокруг более общей - document:messagebox. Формат вызова:

(document:messagebox параметр1 значение1 параметр2 значение2 ...)

Возможные параметры:

• title - заголовок окна
• type - тип окна, один из вариантов: information, question , warning, critical
• message - сообщение
• buttons - список кнопок
• default-button - кнопка по-умолчанию.

Пример:

(document:messagebox
   'type "information"
   'title "Информация"
   'message "Информационное сообщение"
   'buttons '(ok help)
   'default-button 'ok)

Примеры

См. тж. file:///usr/share/alterator/ui/samples/ и местами -- описания в file:///usr/share/alterator/ui/std/. TODO: примеры кода к индивидуальным виджетам