Alterator/Widgets
В интерфейсе Lookout доступны следующие виджеты
Атрибуты, общие для всех виджетов
Взято из alterator-browser-qt/al_widget.cc (кроме colspan и rowspan) по состоянию на 2008/09/22)
visibility | Видимость/невидимость виджета (#t или #f). Если фокус попадает на невидимый виджет - ломается порядок переключения виджетов (мета-атрибут с переопределенным default-get) |
activity | Активность/неактивность виджета (#t или #f). (мета-атрибут с переопределенным default-get) |
tooltip | Справочная информация, выводимая в "пузыре" при наведении на данный виджет. Можно использовать html. Берется только часть строки до первого символа ";" (неочевидно и, возможно, надо исправить!) |
colspan | указание сколько колонок данный виджет займёт внутри "сетки" (целое число) |
rowspan | указание сколько строк данный виджет займёт внутри "сетки" (целое число) |
align | выравнивание (возможные значения: "left" "right" "middle" "hmiddle" "center" "top" "bottom",
можно задать несколько значений, разделяя их символов ';') |
focus | поместить фокус на виджет. Только для записи (#t или #f). |
widget-name | символическое имя виджета - устарел, не должен использоваться! |
title window-title |
заголовок родительского окна (забавно, что его можно выставить из любого виджета. window-title в lookout не определен!) |
max-height | ограничение высоты виджета снизу (целое число) |
min-height | атрибут не определен в lookout |
max-width | ограничение ширины виджета сверху (целое число) |
min-width | атрибут не определен в lookout |
height | фиксированная высота виджета (целое число) |
width | фиксированная ширина виджета (целое число) |
margin | ? |
spacing | ? |
clear-layout | атрибут не определен в lookout |
help | файл справки для главного окна (забавно, что его можно выставить из любого виджета) |
tab-order | атрибут не определен в lookout |
name | Имя виджета. Пока используется для различных эффектов (зависимость активности или видимости виджетов с определенным именем от значения value другого виджета), планируется использовать для автоматического чтения и записи форм. (Метаатрибут) |
Таблица виджетов
Взято из alterator-browser-qt/widgets по состоянию на 2008/09/22 и alterator-lookout.
Жирным шрифтом выделены атрибуты по умолчанию (то есть такие, для которых можно записать (button "ok") вместо (button text "ok")). Впрочем, считается, что не следует использовать эту короткую форму записи.
Кнопки и простые поля ввода:
widget | attributes | events | description |
---|---|---|---|
button | text pixmap |
clicked | кнопка с текстом (и картинкой) |
radio | text state |
toggled | Радиокнопка. Если в одном контейнере есть несколько радиокнопок, отметка одной гасит отметку остальных. |
checkbox | text value (=state) |
toggled changed |
|
edit | value (=text) echo alterability autocompletion-rows |
changed return-pressed |
однострочное текстовое поле ввода; aтрибут autocompletion-rows не определен в lookout; echo = normal/stars/no |
textbox | url text text-append (=append-text) alterability |
changed | многострочное текстовое поле ввода. не хватает атрибута value (=text)? |
spinbox | minimum maximum step value |
changed | поле для ввода чисел |
slider | orientation minimum maximum step value |
changed | orientation = vertical / !vertical |
dateedit | value (=text) expanded |
changed | |
timeedit | value (=text) start stop reset expanded |
changed |
Виджеты оформления (неинтерактивные, без event'ов):
widget | attributes | description |
---|---|---|
label | text text-wrap pixmap |
текст (и картинка) |
progressbar | value minimum maximum text |
|
separator | горизонтальная черта | |
spacer | пустой виджет |
Секреты progressbar'a:
- дефолтное значение границ -- 0..100
- min < val < max -- все нормально
- val < min < max или min < max < val(!), или значение не установлено -- прогресс "на нуле", текст не рисуется(!). При этом, если minimum <=0, то прогресс вообще не рисуется, иначе - рисуется тонкой полоской слева.
- max<min текст рисуется, прогресс не рисуется
- min=max=0 -- "бегающая колбаса"
Простые контейнеры:
widget | attributes | events | description |
---|---|---|---|
groupbox | title state |
toggled | рамка с заголовком |
gridbox | columns | "сетка" для виджетов | |
tabbox | current | selected | |
tab-page | text | страница tabbox'a | |
splitbox | columns | вертикальные колонки с переменным размером (неочевидное поведение, если число виджетов больше числа колонок!) | |
box | |||
vbox | |||
hbox |
Списки объектов:
widget | attributes | events | description |
---|---|---|---|
combobox | append-row rows current current-text alterability rows-clear remove-row row-item-text row-item-pixmap |
selected | выпадающий список |
listbox radiolistbox multilistbox checklistbox |
append-row rows current current-rows state-rows rows-clear remove-row row-item-text row-item-pixmap header enumref value |
selected changed clicked return-pressed double-clicked |
Различные виды списков. Устаревшее название: checklist=checklistbox !!!атрибут value работает только в списке, заполненном с помощью enumref!!! |
tree | tree-items coordinates current header expanded |
selected |
Разное:
widget | attributes | events | description |
---|---|---|---|
slideshow | url /path/to/imgs step Nseconds start stop next prev once |
||
wizardface | title actions action-add action-remove clear action-activity text action-pixmap steps step-add step-remove step-clear step-text step-pixmap current-step |
||
root | width height has-help |
||
dialog(?) | actions action-add action-remove action-clear action-default width height |
Подробное описание виджетов и их атрибутов (местами устарело)
корневой виджет
Именно в этот виджет вставляются все остальные, виджет является или 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 -- возвращает строку с содержимым первого поля активной строки.
- single-select -- таблица с выбором. Для работы в таблице строки должны содержать атрибут name
События:
- selected -- вызывается при изменении активного элемента списка
- clicked -- вызывается при щелчке мышкой по элементу списка
- change -- вызывается при клике на строке списка, у которого выставлен атрибут single-select. Работает только при наличии хотя бы одной строки в таблице.
- double-clicked -- вызывается при двойном щелчке по элементу списка
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: примеры кода к индивидуальным виджетам