Alterator/form: различия между версиями

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


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


Пусть интересующие нас поля ввода (и подписи к ним) имеют атрибуты "name", значение которых совпадает с названиями соответствующих параметров при общении с бакендом. В этом случае можно использовать следующие функции:
Пусть интересующие нас поля ввода (и подписи к ним) имеют атрибуты "name", значение которых совпадает с названиями соответствующих параметров при общении с бакендом. В этом случае можно использовать следующие функции:
Строка 9: Строка 9:
* '''(form-get-elements-by-name name)''' -- получить список виджетов с указанным именем.
* '''(form-get-elements-by-name name)''' -- получить список виджетов с указанным именем.
* '''(form-get-label-by-name name)''' -- получить первый виджет типа "label" с указанным именем.
* '''(form-get-label-by-name name)''' -- получить первый виджет типа "label" с указанным именем.
* '''(form-read url . args-n-names)''' -- прочитать из бакенда (action read) указанные параметры и заполнить соответствующие поля  
* '''(form-read-names names url . args)''' -- прочитать из бакенда (action read) указанные параметры и заполнить соответствующие поля  
* '''(form-write url . args-n-names)''' -- отправить в бакенд (action write) значения полей с указанными именами
* '''(form-write-names names url . args)''' -- отправить в бакенд (action write) значения полей с указанными именами
* '''(form-get name)''' -- получить значение поля с именем name
* '''(form-read url . args)''' -- прочитать данные из бакенда (action read) и заполнть все соответствующие поля
* '''(form-set! name val)''' -- записать значение в поле с именем name
* '''(form-write url . args)''' -- отправить в бакенд (action write) значения всех полей
* '''(form-get-value name)''' -- получить значение поля с именем name
* '''(form-set-value! name val)''' -- записать значение в поле с именем name
* '''(form-apply name . args)''' -- применить args ко всем элементам с именем name и вернуть список результатов.  
* '''(form-apply name . args)''' -- применить args ко всем элементам с именем name и вернуть список результатов.  


Работа с формами происходит в рамках определенного документа (document:root для /std/base).
Работа с формами происходит в рамках определенного документа (document:root для /std/base).
* '''(form-document-get)''' -- возвращает этот документ
* '''(form-get-document)''' -- возвращает этот документ
* '''(form-document-set d)''' -- переопределяет документ
* '''(form-set-document! d)''' -- переопределяет документ
Вряд ли нужно использовать эти функции в интерфейсах.
Вряд ли нужно использовать эти функции в интерфейсах.


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


* '''(form-read/message url . args-n-names)'''
* '''(form-read/message url . args)'''
* '''(form-write/message url . args-n-names)'''
* '''(form-write/message url . args)'''
* '''(form-read-names/message names url . args)'''
* '''(form-write-names/message names url . args)'''


Аргументы '''args-n-names''' функций form-read/write обрабатываются довольно хитрым способом. Если первый аргумент -- список, то это -- параметры, передаваемые бакенду. Все остальные аргументы -- имена виджетов, значения которых надо читать или заполнять. Если имена виджетов не указаны - заполняются все виджеты.
В процедурах form-read/write параметр names -- список строк, параметры args -- дополнительные аргументы, которые передаются в бакенд.


То есть, можно писать, например, так:
То есть, можно писать, например, так:


* '''(form-read "/url")''' -- Чтение информации из бакенда, заполнение всех элементов формы
* '''(form-read "/url")''' -- Чтение информации из бакенда, заполнение всех элементов формы
* '''(form-read "/url" '(par1 "val1"))''' -- то же, но бакенду передается параметр par1=val1
* '''(form-read "/url" 'par1 "val1")''' -- то же, но бакенду передается параметр par1=val1
* '''(form-read "/url" "name1" "name2" "name3")'''
* '''(form-read-names '("name1" "name2" "name3") "/url")'''
* '''(form-read "/url" '(par1 "val1") "name1" "name2" "name3")''' -- то же, но заполняются только указанные поля
* '''(form-read-names '("name1" "name2" "name3") "/url" 'par1 "val1")''' -- то же, но заполняются только указанные поля


===Пример использования===
===Пример использования===
Строка 108: Строка 110:
=== Неочевидное ===
=== Неочевидное ===


* form-read заполняет только интерактивные элементы формы. Если хочется заполнить label - приходится, например, делать скрытый виджет типа edit, заполнять его, а затем вручную переносить значение:  
* Виджеты интерфейса делятся на интерактивные и неинтерактивные. Удобно (например, для использования эффектов) давать одинаковые имена интерактивному виджету и соответствующему виджету-подписи. Функции '''form-read''', '''form-write''', '''form-read-names''', '''form-write-names''', '''form-get-value''', '''form-set-value!''' работают только с интерактивными виджетами. Функции '''form-get-elements-by-name''', '''form-get-label-by-name''', '''form-apply''' работают со всеми виджетами.
 
* Если хочется заполянить параметр неинтерактивного виджета (например, label) из бакенда - можно, например, сделать скрытый виджет типа edit, заполнять его, а затем вручную переносить значение:  


<pre>
<pre>
Строка 114: Строка 118:
(edit name "label"
(edit name "label"
...
...
(form-read "/url" ... "label")
(form-read "/url")
(form-apply "label-name" (form-get "label")
(form-apply "label-name" (form-get "label")
</pre>
</pre>
Строка 121: Строка 125:


* Включить в модуль и в это описание работу с эффектами?
* Включить в модуль и в это описание работу с эффектами?
* Вместо (или дополнительно к) form-apply дать более высокоуровневые функции для работы с аргументами виджетов

Версия от 14:15, 8 октября 2008

Модуль (alterator lookout form)

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

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

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

  • (form-get-elements-by-name name) -- получить список виджетов с указанным именем.
  • (form-get-label-by-name name) -- получить первый виджет типа "label" с указанным именем.
  • (form-read-names names url . args) -- прочитать из бакенда (action read) указанные параметры и заполнить соответствующие поля
  • (form-write-names names url . args) -- отправить в бакенд (action write) значения полей с указанными именами
  • (form-read url . args) -- прочитать данные из бакенда (action read) и заполнть все соответствующие поля
  • (form-write url . args) -- отправить в бакенд (action write) значения всех полей
  • (form-get-value name) -- получить значение поля с именем name
  • (form-set-value! name val) -- записать значение в поле с именем name
  • (form-apply name . args) -- применить args ко всем элементам с именем name и вернуть список результатов.

Работа с формами происходит в рамках определенного документа (document:root для /std/base).

  • (form-get-document) -- возвращает этот документ
  • (form-set-document! d) -- переопределяет документ

Вряд ли нужно использовать эти функции в интерфейсах.

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

  • (form-read/message url . args)
  • (form-write/message url . args)
  • (form-read-names/message names url . args)
  • (form-write-names/message names url . args)

В процедурах form-read/write параметр names -- список строк, параметры args -- дополнительные аргументы, которые передаются в бакенд.

То есть, можно писать, например, так:

  • (form-read "/url") -- Чтение информации из бакенда, заполнение всех элементов формы
  • (form-read "/url" 'par1 "val1") -- то же, но бакенду передается параметр par1=val1
  • (form-read-names '("name1" "name2" "name3") "/url")
  • (form-read-names '("name1" "name2" "name3") "/url" 'par1 "val1") -- то же, но заполняются только указанные поля

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

Было:

(document:surround "/std/base")
 
(define (write-to-backend) 
  (catch/message (lambda() 
    (woo-write "/test" 
      'par1 (mypar1-id value) 
      'par2 (mypar2-id value) 
      'par3 (mypar3-id value) 
      'par4 (mypar4-id value) )))) 
 
(define (read-from-backend) 
  (catch/message (lambda() 
    (let ((data (woo-read-first "/test"))) 
      (mypar1-id value (woo-get-option data 'par1)) 
      (mypar2-id value (woo-get-option data 'par2)) 
      (mypar3-id value (woo-get-option data 'par3)) 
      (mypar4-id value (woo-get-option data 'par4)) )))) 

(gridbox columns "0;100"
  (spacer)
  (document:id mypar1-id (checkbox text (_ "my parameter - 1")))

  (label text (_ "my parameter - 2:") align "right")
  (document:id mypar2-id (edit))

  (label text (_ "m.p. - 3:") align "right")
  (document:id mypar3-id (edit))

  (label text (_ "m.p. - 4:") align "right")
  (document:id mypar4-id (combobox enumref "/test/par4values"))

  (spacer)
  (gridbox columns "0;100"
    (button text (_ "Apply") (when clicked (write-to-backend)))
    (button text (_ "Reset") (when clicked (read-from-backend))) )
)

(document:root (when loaded (read-from-backend)))

Стало:

(document:surround "/std/base")

(gridbox columns "0;100"
  (spacer)
  (checkbox text (_ "my parameter - 1") name "par1"))

  (label text (_ "my parameter - 2:") align "right")
  (edit name "par2")

  (label text (_ "m.p. - 3:") align "right")
  (edit name "par3")

  (label text (_ "m.p. - 4:") align "right")
  (combobox enumref "/test/par4values" name "par4")

  (spacer)
  (gridbox columns "0;100"
    (button text (_ "Apply") (when clicked (form-write/message "/test")))
    (button text (_ "Reset") (when clicked (form-read/message "/test"))) )
)

(document:root (when loaded (read-from-backend)))

Неочевидное

  • Виджеты интерфейса делятся на интерактивные и неинтерактивные. Удобно (например, для использования эффектов) давать одинаковые имена интерактивному виджету и соответствующему виджету-подписи. Функции form-read, form-write, form-read-names, form-write-names, form-get-value, form-set-value! работают только с интерактивными виджетами. Функции form-get-elements-by-name, form-get-label-by-name, form-apply работают со всеми виджетами.
  • Если хочется заполянить параметр неинтерактивного виджета (например, label) из бакенда - можно, например, сделать скрытый виджет типа edit, заполнять его, а затем вручную переносить значение:
(label name "lable-name")
(edit name "label"
...
(form-read "/url")
(form-apply "label-name" (form-get "label")

TODO

  • Включить в модуль и в это описание работу с эффектами?
  • Вместо (или дополнительно к) form-apply дать более высокоуровневые функции для работы с аргументами виджетов