Alterator/form

Материал из ALT Linux Wiki

Версия 16:24, 2 февраля 2009

Модуль (alterator lookout form)

Адресация полей

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

Пример:

(label text "Field name" name "field")(edit name "field" value "Field value")

Исключение - в качестве поля выступает виджет label. В этом случае метки с тем значением атрибута name быть не должно.

Пример:

(label name "field" value "Field label") ;; Ошибка!!!
(label name "field" value "Static field")

В этом модуле сделана попытка упростить работу со стандартными диалогами, практически убрав необходимость адресовать виджеты с помощью document:id.

Кроме того, этот модуль используется при работе с эффектами в модуле (alterator loоkout effects).

Описание относится к alterator-lookout-1.4-alt3. Интерфейс библиотеки, вероятно, ещё не застабилизировался, поэтому массово применять её пока не рекомендуется.

Примеры использования — в модулях alterator-{xinetd, datetime}

…

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

Работа с виджетами

• (form-get-elements-by-name document name) — Получить список виджетов с указанным именем
• (form-element-apply document name . args) — Применить args ко всем виджетам с именем name и вернуть список результатов
• (form-get-label document name) — Получить первый виджет типа label с указанным именем. Сейчас используется только при выводе сообщений об ошибках несоответствия типа.
• (form-get-input document name) — Получить поле ввода с указанным именем. Поля ввода — это виджеты одного из типов (checkbox edit listbox spinbox slider timeedit dateedit combobox listbox textbox radiolistbox multilistbox checklistbox), значения которых мы хотим получать из бэкенда и передавать обратно. Функция вываливается с исключением form-error, если таких полей больше одного.
• (form-input-get-value document name) — получить значение поля с именем name
• (form-input-set-value! document name val) — записать значение в поле с именем name

Работа с бэкендом:

• (form-read document url . args) — прочитать данные из бэкенда (action read) и заполнить все соответствующие поля
• (form-write document url . args) — отправить в бэкенд (action write) значения всех полей
• (form-read-names document names url . args) — прочитать из бэкенда (action read) указанные параметры и заполнить соответствующие поля
• (form-write-names document names url . args) — отправить в бэкенд (action write) значения полей с указанными именами

Здесь document — документ в рамках которого происходит поиск виджетов. url и args — аргументы для общения с бэкендом…

Кроме того, в /std/base определены обёртки, устанавливающие document в document:root, а также выводящие окно предупреждения при ошибках в общении с бэкендом:

• (form-get-value name) = (form-input-get-value document::root name)
• (form-set-value! name value) = (form-input-set-value! document::root name value)
• (form-apply name . args)
• (form-read/message url . args)
• (form-write/message url . args)
• (form-read-names/message names url . args)
• (form-write-names/message names url . args)

Пример использования

Было:

"/std/base""/test""/test""0;100""my parameter - 1""my parameter - 2:""right""m.p. - 3:""right""m.p. - 4:""right""/test/par4values""0;100""Apply""Reset"

Стало:

"/std/base""0;100""my parameter - 1""par1""my parameter - 2:""right""par2""m.p. - 3:""right""par3""m.p. - 4:""right""/test/par4values""par4""0;100""Apply""/test""Reset""/test"

Неочевидное + TODO

• Если хочется заполянить параметр неинтерактивного виджета (например, label) из бэкенда — можно, например, сделать скрытый виджет типа edit, заполнять его, а затем вручную переносить значение:

(label name "label2")
(edit name "label" visibility #f)
...
(form-read "/url")
(form-element-apply "label2" (form-input-get-value "label"))

TODO

• сделать специальный алиас для label, который бы при общении с бэкендом трактовался как поле ввода (и имел атрибут value)…
• переименовать form-get-elements-by-name -> form-get-elements (по аналогии с остальными функциями form-get-input, form-get-label)
• переименовать form-element-apply -> form-elements-apply (т.к. она действует на все элементы с заданным именем, точно так же, как и form-get-elements-by-name)
• вернуть функции form-{get,set}-document для определения текущего документа, убрать соответствующие обертки из /std/base. (Наличие оберток с непохожими именами - явное зло. С другой стороны, явно указывать во всех вызовах документ тоже не хочется, поскольку его можно установить один раз в /std/base и о нем почти всегда вообще не думать)