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 -- вызывается при двойном щелчке по элементу списка

Примечание: Щёлкания могут перекрывать друг друга в случае 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: примеры кода к индивидуальным виджетам