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

Материал из ALT Linux Wiki
(→‎общие атрибуты: Запрет изменения элемента формы)
 
(не показано 29 промежуточных версий 4 участников)
Строка 1: Строка 1:
[[Category:Sisyphus]]
<onlyinclude>
{{MovedFromFreesourceInfo|AltLinux/Sisyphus/Alterator/module/interface}}
 
=== Интерфейс ===
=== Интерфейс ===
Основу интерфейса модуля составляют формы - графическое отображение параметров того или иного объекта системы. При создании интерфейсов следует придерживаться определённых правил, чтобы интерфейс был единообразен и понятен для пользователя. На данный момент интерфейс имеет отдельное описание для qt и отдельное описание для html. В обоих случаях описание носит декларативный характер и состоит из описания местоположения виджетов и привязки интерфейса к соответствующему бакенду.
Основу интерфейса модуля составляют формы графическое отображение параметров того или иного объекта системы. При создании интерфейсов следует придерживаться определённых правил, чтобы интерфейс был единообразен и понятен для пользователя. На данный момент интерфейс имеет отдельное описание для qt и отдельное описание для html. В обоих случаях описание носит декларативный характер и состоит из описания местоположения виджетов и привязки интерфейса к соответствующему бэкенду.


==== Простейший интерфейс для qt ====
==== Простейший интерфейс для qt ====
<pre>(document:support "/std/frame")
<source lang="lisp">
(document:support "/std/frame")


(label text "test" name "mylabel")</pre>
(label text "test" name "mylabel")
Интерфейс описывается на подмножестве языка scheme. Заголовок включает все необходимые определения из стандартной библиотеки, далее следует описание элементов интерфейса. Взаимодействие с бакендом осуществляется путём вызова функций woo-*.
</source>
Интерфейс описывается на подмножестве языка scheme. Заголовок включает все необходимые определения из стандартной библиотеки, далее следует описание элементов интерфейса. Взаимодействие с бэкендом осуществляется путём вызова функций woo-*.


==== Простейший интерфейс для html ====
==== Простейший интерфейс для html ====
<pre><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">
<source lang="html4strict">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">
<html wf="form">
<html wf="form">
   <head>
   <head>
Строка 22: Строка 23:
     </form>
     </form>
   </body>
   </body>
</html></pre>
</html>
В alterator принято использовать запись в стиле xhtml. Описание статическое и декларативное, вся динамика и привязка к бакенду скрыта в workflow, указанным в теге <tt>html</tt> в атрибуте <tt>wf</tt>. По умолчанию адрес бакенда совпадает с адресом описания интерфейса.
</source>
В alterator принято использовать запись в стиле xhtml. Описание статическое и декларативное, вся динамика и привязка к бэкенду скрыта в workflow, указанным в теге <tt>html</tt> в атрибуте <tt>wf</tt>. По умолчанию адрес бэкенда совпадает с адресом описания интерфейса.


==== Формы ====
==== Формы ====
Форма -- это графическое представление интерфейса некоторого объекта системы. При создании дизайна формы следует руководствоваться простым правилом -- названия полей не должны быть "оторваны" от самих полей.
Форма это графическое представление интерфейса некоторого объекта системы. При создании дизайна формы следует руководствоваться простым правилом названия полей не должны быть "оторваны" от самих полей.


Пример правильного описания для qt:
Пример правильного описания для qt:
<pre>(gridbox columns "0;100"
<source lang="lisp">
(gridbox columns "0;100"


   (label "Label:" align "right")
   (label "Label:" align "right")
Строка 35: Строка 38:


   (label "Label:" align "right")
   (label "Label:" align "right")
   (field))</pre>
   (field))
Обратите внимание на "0" для колонки с метками - это необходимо, чтобы колонка заняла в ширину ровно столько сколько необходимо для самой длинной метки.
</source>
Обратите внимание на "0" для колонки с метками это необходимо, чтобы колонка заняла в ширину ровно столько сколько необходимо для самой длинной метки.


Пример правильного описания для html:
Пример правильного описания для html:
<pre><table class="form-table">
<source lang="html4strict">
<table class="form-table">
   <tr>
   <tr>
     <td>Label:</td>
     <td>Label:</td>
Строка 48: Строка 53:
     <td>Field</td>
     <td>Field</td>
   </tr>
   </tr>
</table></pre>
</table>
</source>
CSS-класс "form-table" не будет корректно работать для старых браузеров (Internet Explorer 6.0), для них необходимо во всех td, содержащих метки использовать CSS-класс "form-table-label".
CSS-класс "form-table" не будет корректно работать для старых браузеров (Internet Explorer 6.0), для них необходимо во всех td, содержащих метки использовать CSS-класс "form-table-label".


Строка 55: Строка 61:


'''Группировка при помощи пустых строк'''
'''Группировка при помощи пустых строк'''
 
{|
Пример для html:
!align="right"|html:
<pre><td colspan="2">&nbsp;</td></pre>
|<tt><nowiki><td colspan="2">&amp;nbsp;</td></nowiki></tt>
 
|-
Пример для qt:
!align="right"|qt:
<pre>(label colspan "2")</pre>
|<tt>(label colspan "2")</tt>
|-
|}


'''Группировка при помощи горизонтальной черты'''
'''Группировка при помощи горизонтальной черты'''
Пример для html:
{|
<pre><td colspan="2"><hr/></td></pre>
!align="right"|html:
 
|<tt><nowiki><td colspan="2"><hr /></td></nowiki></tt>
Пример для qt:
|-
<pre>(separator colspan="2")</pre>
!align="right"|qt:
|<tt>(separator colspan="2")</tt>
|-
|}


В этом способе группировки возможно задание названия группы. Название группы делается полужирным шрифтом и выравнено по левому краю формы.  
В этом способе группировки возможно задание названия группы. Название группы делается полужирным шрифтом и выравнено по левому краю формы.  
Пример для html:
{|
<pre><td><strong>Group title</strong></td></pre>
!align="right"|html:
 
|<tt><nowiki><td><strong>Group title</strong></td></nowiki></tt>
Пример для qt:
|-
<pre>(label text (bold "Group title") align "right")</pre>
!align="right"|qt:
|<tt>(label text (bold "Group title") align "right")</tt>
|-
|}


==== Простейшее форматирование текста ====
==== Простейшее форматирование текста ====
Строка 82: Строка 96:
{|
{|
!align="right"|html:
!align="right"|html:
|&lt;strong&gt;some text&lt;/strong&gt;
|<tt><nowiki><strong>some text</strong></nowiki></tt>
|-
|-
!align="right"|qt:
!align="right"|qt:
|(bold "some text")
|<tt>(bold "some text")</tt>
|-
|-
|}
|}
Строка 92: Строка 106:
{|
{|
!align="right"|html:
!align="right"|html:
|&lt;small&gt;some text&lt;/small&gt;
|<tt><nowiki><small>some text</small></nowiki></tt>
|-
|-
!align="right"|qt:
!align="right"|qt:
|(small "some text")
|<tt>(small "some text")</tt>
|-
|-
|}
|}
Строка 106: Строка 120:


===== общие атрибуты =====
===== общие атрибуты =====
Если элемент формы надо скрыть, то в html для этого есть параметры CSS, а в qt -- атрибут <tt>visibility</tt>.
Если элемент формы надо скрыть, то в html для этого есть параметры CSS, а в qt атрибут <tt>visibility</tt>.
 


Пример для qt:
Пример для qt:
<pre>(edit) ;; видимое поле
<source lang="lisp">
(edit) ;; видимое поле
(edit visibility #t) ;; видимое поле
(edit visibility #t) ;; видимое поле
(edit visibility #f) ;; невидимое поле</pre>
(edit visibility #f) ;; невидимое поле
</source>


Пример для html:
Пример для html:
<pre><input type="text" class="text"/> <!-- видимое поле -->
<source lang="html4strict">
<input type="text" class="text"/> <!-- видимое поле -->
<input type="text" class="text" style="display:inline" /> <!-- видимое поле -->
<input type="text" class="text" style="display:inline" /> <!-- видимое поле -->
<input type="text" class="text" style="display:none" /> <!-- невидимое поле --></pre>
<input type="text" class="text" style="display:none" /> <!-- невидимое поле -->
</source>
 
Если надо запретить изменение элемента формы, то в html для этого есть признак <tt>readonly</tt>, а в qt — атрибут <tt>alterability</tt>.
 
Пример для qt:
<source lang="lisp">
(edit) ;; изменяемое поле
(edit alterability #t) ;; изменяемое поле
(edit alterability #f) ;; неизменяемое поле
</source>
 
Пример для html:
<source lang="html4strict">
<input type="text" class="text" /> <!-- изменяемое поле -->
<input type="text" class="text" readonly /> <!-- неизменяемое поле -->
</source>


===== сheckbox =====
===== сheckbox =====
Строка 124: Строка 156:
{|
{|
!align="right"|html:
!align="right"|html:
|&lt;input type="checkbox"/&gt;Label for checkbox
|<tt><nowiki><input type="checkbox" />Label for checkbox</nowiki></tt>
|-
|-
!align="right"|qt:
!align="right"|qt:
|(checkbox text "Label for checkbox")
|<tt>(checkbox text "Label for checkbox")</tt>
|-
|-
|}
|}
Строка 135: Строка 167:
При создании интерфейса пожалуйста следите за тем что метка к checkbox '''должна''' идти после галочки и начинаться с заглавной буквы.
При создании интерфейса пожалуйста следите за тем что метка к checkbox '''должна''' идти после галочки и начинаться с заглавной буквы.


Пример работы в бакенде на shell:
Пример работы в бэкенде на shell:
<pre>read)
<source lang="bash">
      read)
             ...
             ...
             write_bool_param"item1" "Yes"
             write_bool_param"item1" "Yes"
       write)
       write)
             if test_bool "$in_item1"; then ...  else ... fi</pre>
             if test_bool "$in_item1"; then ...  else ... fi
</source>


Функция <tt>write_bool_param</tt> принимает два параметра - имя и значение. В качестве значения допустимы любые варианты: y, yes, on, true (в любом регистре). Функция <tt>test_bool</tt> применяется для "считывания" значения параметра, независимым от представления в протоколе виде.
Функция <tt>write_bool_param</tt> принимает два параметра имя и значение. В качестве значения допустимы любые варианты: y, yes, on, true (в любом регистре). Функция <tt>test_bool</tt> применяется для "считывания" значения параметра, независимым от представления в протоколе виде.


===== button =====
===== button =====
Строка 148: Строка 182:
{|
{|
!align="right"|html:
!align="right"|html:
|&lt;input type="submit" class="btn" name="somename" value="Button name"/&gt;
|<tt><nowiki><input type="submit" class="btn" name="somename" value="Button name" /></nowiki></tt>
|-
|-
!align="right"|qt:
!align="right"|qt:
|(button text "Button name")
|<tt>(button text "Button name")</tt>
|-
|-
|}
|}
Строка 163: Строка 197:
===== combobox/listbox/select =====
===== combobox/listbox/select =====
В самом простом случае данные элементы представляют атрибут типа перечисление (enum), то есть обеспечивают выбор одного варианта
В самом простом случае данные элементы представляют атрибут типа перечисление (enum), то есть обеспечивают выбор одного варианта
из числа возможных. Сombobox - более компактное представление чем Listbox, но одновременно выдно только один вариант, чтобы просмотреть остальные - надо вызвать выпадающий список.  
из числа возможных. Сombobox более компактное представление чем Listbox, но одновременно видно только один вариант, чтобы просмотреть остальные надо вызвать выпадающий список.  
Список вариантов предоставляет бакенд (вызываемый с action list). Параметр <tt>enumref</tt> - адрес к которому надо обращаться к бакенду за списком.
Список вариантов предоставляет бэкенд (вызываемый с action list). Параметр <tt>enumref</tt> адрес к которому надо обращаться к бэкенду за списком.
 
'''Компактное представление списка:'''
{|
!align="right"|html:
|<tt><nowiki><select name="item1" enumref="/x11/avail_resolution" /></nowiki></tt>
|-
!align="right"|qt:
|<tt>(combobox enumref "/x11/avail_resolution")</tt>
|-
|}


Пример для qt:
'''Развёрнутое представление списка:'''
<pre>(combobox enumref "/x11/avail_resolution") ;;компактное представление списка
{|
(listbox enumref "/x11/avail_driver") ;; развёрнутое представление списка</pre>
!align="right"|html:
Текущий выбранный вариант - параметр <tt>value</tt>.
|<tt><nowiki><select name="item1" size="10" enumref="/x11/avail_driver" /></nowiki></tt>
|-
!align="right"|qt:
|<tt>(listbox enumref "/x11/avail_driver")</tt>
|-
|}


Пример для html:
В qt текущий выбранный вариант — параметр <tt>value</tt>. В html интерфейсе размер списка в строках параметр <tt>size</tt>. Обратите также внимание на написание тега в стиле xml, а не html.
<pre><select name="item1" enumref="/x11/avail_resolution"/> <!-- компактное представление списка -->
<select name="item1" size="10" enumref="/x11/avail_driver"/> <!-- развёрнутое представление списка --></pre>
Размер списка в строках - параметр <tt>size</tt>. Обратите внимание на написание тега в стиле xml, а не html.  


Пример бакенда на shell:
Пример бэкенда на shell:
<pre>...
<source lang="bash">
...
       list)
       list)
         write_enum_item "item1" "label1"
         write_enum_item "item1" "label1"
Строка 188: Строка 235:
         echo "$in_name">zzz
         echo "$in_name">zzz
         ;;
         ;;
...</pre>
...
</source>
 
Функция write_enum_item принимает два параметра:
Функция write_enum_item принимает два параметра:
* вариант - то ключевое имя, которым пользуется бакенд
* вариант то ключевое имя, которым пользуется бэкенд
* название варианта (необязательно) - то описание, которое будет выведено пользователю (возможно с переводом)
* название варианта (необязательно) то описание, которое будет выведено пользователю (возможно с переводом)
Если функция вызвана без параметра, то она начинает со стандартного ввода строки с одним или более значениями, разделённых стандартным разделителем (переменная IFS). Первое и второе значение интерпретируются также: вариант и его название.


===== checklistbox =====
===== checklistbox =====
Также как и listbox представляет атрибут перечислимого типа, но уже с возможностью множественного выбора. Для заполнения списка используется тот же параметр <tt>enumref</tt>. Для "массового" выделения бакенд должен выводить список имён, в бакенд результат возвращается также в виде списка . Список представляется в виде строки с разделителем ";", например "a;b;c;d".
Также как и listbox представляет атрибут перечислимого типа, но уже с возможностью множественного выбора. Для заполнения списка используется тот же параметр <tt>enumref</tt>. Для "массового" выделения бэкенд должен выводить список имён, в бэкенд результат возвращается также в виде списка . Список представляется в виде строки с разделителем ";", например "a;b;c;d".
 
{|
!align="right"|html:
|<tt><nowiki><table class="alterator-checklistbox" enumref="/dovecot/avail_mechanisms" name="mechanisms" /></nowiki></tt>
|-
!align="right"|qt:
|<tt>(checklistbox enumref "/dovecot/avail_mechanisms")</tt>
|-
|}
 
В qt текущий набор выделенных элементов — параметр <tt>value</tt>.
 
===== многоколоночный listbox =====
Вариант listbox с отображением информации разбитой на несколько колонок для более удобного чтения. Иначе говоря отображение таблиц. Источник данных для таблиц — бэкенд, адрес указывается при помощи атрибута <strong>enumref</strong>. В таблице есть ключевое поле. При помощи ключевого поля идентифицируется текущее значение таблицы точно также как это делалось для одноколоночного варианта. Для вывода информации бэкенд пользуется функцией <strong>write_table_item</strong>: write_table_item &lt;парметр1&gt; &lt;значение1&gt; &lt;параметр2&gt; &lt;значение2&gt; ...
 
В qt интерфейсе при помощи атрибута <strong>row</strong> задаётся шаблон строки таблицы:
<source lang="lisp">'#((label1 . pixmap1) (label2 . pixmap2))</source>.
Здесь label1,label2,pixmap1,pixmap2 — символы — имена параметров переданных бэкендом. Таким образом в зависимости от информации в строках будут различаться и текстовое и графическое содержимое строк.


Пример для qt:
Пример:
<pre>(checklistbox enumref "/dovecot/avail_mechanisms")</pre>
<source lang="lisp">
Текущий набор выделенных элементов - параметр <tt>value</tt>.
(listbox columns 2
          row '#((name . "") (summary . ""))
          header (vector (_ "Facility") (_ "Summary"))
          enumref "/control")
</source>
 
В html интерфейсе шаблон строки таблицы задаётся внутри тега &lt;tbody&gt;. Для каждой строки переданной бэкендом указанная строка "заполняется" и таким образом "размножается".


Пример для html:
Пример:
<pre><table class="alterator-checklistbox" enumref="/dovecot/avail_mechanisms" name="mechanisms" /></pre>
<source lang="html4strict">
<table class="alterator-listbox" enumref="/control">
  <thead>
  <tr>
    <th><span translate="_">Facility</span></th>
    <th><span translate="_">Summary</span></th>
    <th><span translate="_">State</span></th>
  </tr>
  </thead>
  <tbody>
  <tr>
  <td nowrap="yes">
    <a href="/control/facility?fname=" class="alterator-ref2">
      <span class="alterator-label" name="name"></span>
    </a>
  </td>
  <td><span class="alterator-label" name="summary"/>&nbsp;</td>
  <td><span class="alterator-label" name="current"/></td>
  </tr>
  </tbody>
</table>
</source>


===== edit =====
===== edit =====
Представляет атрибут строкового типа.
Представляет атрибут строкового типа.
{|
!align="right"|html:
|<tt><nowiki><input type="text" class="text" name="name1" /></nowiki></tt>
|-
!align="right"|qt:
|<tt>(edit)</tt>
|-
|}
Для ввода пароля есть специальный вариант edit.


Пример для qt:
{|
<pre>(edit)</pre>
!align="right"|html:
Для изменения и получения значения служит атрибут <tt>value</tt>.
|<tt><nowiki><input type="password" class="text" name="name" /></nowiki></tt>
|-
!align="right"|qt:
|<tt>(edit echo "stars")</tt>
|-
|}


Пример для html:
В qt для изменения и получения значения служит атрибут <tt>value</tt>.
<pre><input type="text" class="text" name="name1"/></pre>


Пример бакенда на shell:
Пример бэкенда на shell:
<pre>...
<source lang="bash">
...
       read)
       read)
         write_string_param name1 "value1"
         write_string_param name1 "value1"
         ;;
         ;;
       write)
       write)
         echo $in_name1" >zzz
         echo "$in_name1" >zzz
       ;;
       ;;
..</pre>
...
</source>
Функция write_string_param принимает два атрибута: имя и значение.
Функция write_string_param принимает два атрибута: имя и значение.


Для ввода пароля есть специальный вариант edit.
===== dateedit =====
Специализированный виджет в виде календаря и текстового поля для работы с датой &mdash; строкой формата ''ГГГГ-ММ-ДД''. Имеются два варианта виджета: развёрнутый и компактный. Во втором случае календарь появляется под полем ввода при нажатии на специальную клавишу.


Пример для qt:
Развернутый вариант:
<pre>(edit echo "stars")</pre>


Пример для html:
{|
<pre><input type="password" class="text" name="name"/></pre>
!align="right"|html:
|<tt><nowiki><div class="alterator-dateedit" name="name" /></nowiki></tt>
|-
!align="right"|qt:
|<tt>(dateedit expanded #t)</tt>
|-
|}


===== dateedit =====
Компактный вариант:
Специализированный виджет в виде календаря и текстового поля для работы с датой &mdash; строкой формата ''ГГГГ-ММ-ДД''.


{|
{|
!align="right"|html:
!align="right"|html:
|&lt;div class="alterator-dateedit" name="name"/&gt;
|<tt><nowiki><span class="alterator-dateedit" name="name" /></nowiki></tt>
|-
|-
!align="right"|qt:
!align="right"|qt:
|(dateedit expanded #t)
|<tt>(dateedit expanded #f)</tt>
|-
|-
|}
|}


Для получения и изменения значения в qt используйте атрибут <tt>value</tt>. В web-интерфейсе календарь будет работать только в браузерах с включенной поддержкой Javascript.
Для получения и изменения значения в qt используйте атрибут <tt>value</tt>. В web-интерфейсе календарь будет работать только в браузерах с включенной поддержкой Javascript.
Строка 251: Строка 366:
{|
{|
!align="right"|html:
!align="right"|html:
|&lt;div class="alterator-timeedit" name="name"/&gt;
|<tt><nowiki><div class="alterator-timeedit" name="name" /></nowiki></tt>
|-
|-
!align="right"|qt:
!align="right"|qt:
|(timeedit expanded #t)
|<tt>(timeedit expanded #t)</tt>
|-
|-
|}
|}


Для получения и изменения значения в qt используйте атрибут <tt>value</tt>. В html интерфейсе часы будут работать только в браузерах с включенной поддержкой Javascript.
Для получения и изменения значения в qt используйте атрибут <tt>value</tt>. В html интерфейсе часы будут работать только в браузерах с включенной поддержкой Javascript.
</onlyinclude>
{{Alterator modules-nav}}

Текущая версия от 17:06, 28 сентября 2015

Интерфейс

Основу интерфейса модуля составляют формы — графическое отображение параметров того или иного объекта системы. При создании интерфейсов следует придерживаться определённых правил, чтобы интерфейс был единообразен и понятен для пользователя. На данный момент интерфейс имеет отдельное описание для qt и отдельное описание для html. В обоих случаях описание носит декларативный характер и состоит из описания местоположения виджетов и привязки интерфейса к соответствующему бэкенду.

Простейший интерфейс для qt

(document:support "/std/frame")

(label text "test" name "mylabel")

Интерфейс описывается на подмножестве языка scheme. Заголовок включает все необходимые определения из стандартной библиотеки, далее следует описание элементов интерфейса. Взаимодействие с бэкендом осуществляется путём вызова функций woo-*.

Простейший интерфейс для html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">
<html wf="form">
  <head>
    <title>Some module</title>
  </head>
  <body>
    <form>
            <div class="alterator-text" name="url"/>
    </form>
  </body>
</html>

В alterator принято использовать запись в стиле xhtml. Описание статическое и декларативное, вся динамика и привязка к бэкенду скрыта в workflow, указанным в теге html в атрибуте wf. По умолчанию адрес бэкенда совпадает с адресом описания интерфейса.

Формы

Форма — это графическое представление интерфейса некоторого объекта системы. При создании дизайна формы следует руководствоваться простым правилом — названия полей не должны быть "оторваны" от самих полей.

Пример правильного описания для qt:

(gridbox columns "0;100"

   (label "Label:" align "right")
   (field)

   (label "Label:" align "right")
   (field))

Обратите внимание на "0" для колонки с метками — это необходимо, чтобы колонка заняла в ширину ровно столько сколько необходимо для самой длинной метки.

Пример правильного описания для html:

<table class="form-table">
  <tr>
    <td>Label:</td>
    <td>Field</td>
  </tr>
  <tr>
    <td>Label:</td>
    <td>Field</td>
  </tr>
</table>

CSS-класс "form-table" не будет корректно работать для старых браузеров (Internet Explorer 6.0), для них необходимо во всех td, содержащих метки использовать CSS-класс "form-table-label".

Группировка элементов формы

Иногда интерфейс становится столь большим, что приходится группировать отдельные его части.

Группировка при помощи пустых строк

html: <td colspan="2">&nbsp;</td>
qt: (label colspan "2")

Группировка при помощи горизонтальной черты

html: <td colspan="2"><hr /></td>
qt: (separator colspan="2")

В этом способе группировки возможно задание названия группы. Название группы делается полужирным шрифтом и выравнено по левому краю формы.

html: <td><strong>Group title</strong></td>
qt: (label text (bold "Group title") align "right")

Простейшее форматирование текста

Для форматирования текста рекомендуется пользоваться только ниже перечисленными способами.

текст полужирным шрифтом
html: <strong>some text</strong>
qt: (bold "some text")
текст мелким шрифтом
html: <small>some text</small>
qt: (small "some text")

Элементы формы

Форма состоит из различных элементов. При размещении элементов стоит руководствоваться следующими правилами:

  • Метки полей и заголовки должны начинаться с заглавной буквы.
  • Если метка и поле находятся в одной строке, то метка должна заканчиваться символом двоеточия ":".
  • Заголовки групп, включая заголовки groupbox не должны содержать символа двоеточия ":".
общие атрибуты

Если элемент формы надо скрыть, то в html для этого есть параметры CSS, а в qt — атрибут visibility.

Пример для qt:

(edit) ;; видимое поле
(edit visibility #t) ;; видимое поле
(edit visibility #f) ;; невидимое поле

Пример для html:

<input type="text" class="text"/> <!-- видимое поле -->
<input type="text" class="text" style="display:inline" /> <!-- видимое поле -->
<input type="text" class="text" style="display:none" /> <!-- невидимое поле -->

Если надо запретить изменение элемента формы, то в html для этого есть признак readonly, а в qt — атрибут alterability.

Пример для qt:

(edit) ;; изменяемое поле
(edit alterability #t) ;; изменяемое поле
(edit alterability #f) ;; неизменяемое поле

Пример для html:

<input type="text" class="text" /> <!-- изменяемое поле -->
<input type="text" class="text" readonly /> <!-- неизменяемое поле -->
сheckbox

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

html: <input type="checkbox" />Label for checkbox
qt: (checkbox text "Label for checkbox")

Для получения/изменения значения пользуйтесь атрибутом value. Обратите внимание на написание тега в стиле xml, а не html.

При создании интерфейса пожалуйста следите за тем что метка к checkbox должна идти после галочки и начинаться с заглавной буквы.

Пример работы в бэкенде на shell:

      read)
            ...
            write_bool_param"item1" "Yes"
      write)
            if test_bool "$in_item1"; then ...  else ... fi

Функция write_bool_param принимает два параметра — имя и значение. В качестве значения допустимы любые варианты: y, yes, on, true (в любом регистре). Функция test_bool применяется для "считывания" значения параметра, независимым от представления в протоколе виде.

button

Данный элемент предназначен для представления активных действий с формой.

html: <input type="submit" class="btn" name="somename" value="Button name" />
qt: (button text "Button name")

Обратите внимание на использование класса btn и на написание тега в стиле xml, а не html.

При построении интерфейса постарайтесь следовать следующим правилам:

  • Текст кнопок должен начинаться с заглавной буквы
  • Если кнопка открывает дополнительное диалоговое окно, то текст кнопки должен заканчиватья многоточием "..."
  • Ни один диалог модуля не должен содержать кнопки "Выход"
combobox/listbox/select

В самом простом случае данные элементы представляют атрибут типа перечисление (enum), то есть обеспечивают выбор одного варианта из числа возможных. Сombobox — более компактное представление чем Listbox, но одновременно видно только один вариант, чтобы просмотреть остальные — надо вызвать выпадающий список. Список вариантов предоставляет бэкенд (вызываемый с action list). Параметр enumref — адрес к которому надо обращаться к бэкенду за списком.

Компактное представление списка:

html: <select name="item1" enumref="/x11/avail_resolution" />
qt: (combobox enumref "/x11/avail_resolution")

Развёрнутое представление списка:

html: <select name="item1" size="10" enumref="/x11/avail_driver" />
qt: (listbox enumref "/x11/avail_driver")

В qt текущий выбранный вариант — параметр value. В html интерфейсе размер списка в строках — параметр size. Обратите также внимание на написание тега в стиле xml, а не html.

Пример бэкенда на shell:

...
      list)
        write_enum_item "item1" "label1"
        write_enum_item "item2" "label2"
        ;;
      read)
        write_string_param "name" "item1"
        ;;
      write)
        echo "$in_name">zzz
        ;;
...

Функция write_enum_item принимает два параметра:

  • вариант — то ключевое имя, которым пользуется бэкенд
  • название варианта (необязательно) — то описание, которое будет выведено пользователю (возможно с переводом)
checklistbox

Также как и listbox представляет атрибут перечислимого типа, но уже с возможностью множественного выбора. Для заполнения списка используется тот же параметр enumref. Для "массового" выделения бэкенд должен выводить список имён, в бэкенд результат возвращается также в виде списка . Список представляется в виде строки с разделителем ";", например "a;b;c;d".

html: <table class="alterator-checklistbox" enumref="/dovecot/avail_mechanisms" name="mechanisms" />
qt: (checklistbox enumref "/dovecot/avail_mechanisms")

В qt текущий набор выделенных элементов — параметр value.

многоколоночный listbox

Вариант listbox с отображением информации разбитой на несколько колонок для более удобного чтения. Иначе говоря отображение таблиц. Источник данных для таблиц — бэкенд, адрес указывается при помощи атрибута enumref. В таблице есть ключевое поле. При помощи ключевого поля идентифицируется текущее значение таблицы точно также как это делалось для одноколоночного варианта. Для вывода информации бэкенд пользуется функцией write_table_item: write_table_item <парметр1> <значение1> <параметр2> <значение2> ...

В qt интерфейсе при помощи атрибута row задаётся шаблон строки таблицы:

'#((label1 . pixmap1) (label2 . pixmap2))

.

Здесь label1,label2,pixmap1,pixmap2 — символы — имена параметров переданных бэкендом. Таким образом в зависимости от информации в строках будут различаться и текстовое и графическое содержимое строк.

Пример:

 (listbox columns 2
          row '#((name . "") (summary . ""))
          header (vector (_ "Facility") (_ "Summary"))
          enumref "/control")

В html интерфейсе шаблон строки таблицы задаётся внутри тега <tbody>. Для каждой строки переданной бэкендом указанная строка "заполняется" и таким образом "размножается".

Пример:

<table class="alterator-listbox" enumref="/control">
  <thead>
   <tr>
     <th><span translate="_">Facility</span></th>
     <th><span translate="_">Summary</span></th>
     <th><span translate="_">State</span></th>
   </tr>
  </thead>
  <tbody>
  <tr>
   <td nowrap="yes">
     <a href="/control/facility?fname=" class="alterator-ref2">
       <span class="alterator-label" name="name"></span>
     </a>
   </td>
   <td><span class="alterator-label" name="summary"/>&nbsp;</td>
   <td><span class="alterator-label" name="current"/></td>
  </tr>
  </tbody>
</table>
edit

Представляет атрибут строкового типа.

html: <input type="text" class="text" name="name1" />
qt: (edit)

Для ввода пароля есть специальный вариант edit.

html: <input type="password" class="text" name="name" />
qt: (edit echo "stars")

В qt для изменения и получения значения служит атрибут value.

Пример бэкенда на shell:

...
      read)
        write_string_param name1 "value1"
        ;;
      write)
         echo "$in_name1" >zzz
       ;;
...

Функция write_string_param принимает два атрибута: имя и значение.

dateedit

Специализированный виджет в виде календаря и текстового поля для работы с датой — строкой формата ГГГГ-ММ-ДД. Имеются два варианта виджета: развёрнутый и компактный. Во втором случае календарь появляется под полем ввода при нажатии на специальную клавишу.

Развернутый вариант:

html: <div class="alterator-dateedit" name="name" />
qt: (dateedit expanded #t)

Компактный вариант:

html: <span class="alterator-dateedit" name="name" />
qt: (dateedit expanded #f)


Для получения и изменения значения в qt используйте атрибут value. В web-интерфейсе календарь будет работать только в браузерах с включенной поддержкой Javascript.

timeedit

Специализированный виджет в виде аналоговых часов и текстового поля для работы со временем — строкой формата ЧЧ:ММ:CC.

html: <div class="alterator-timeedit" name="name" />
qt: (timeedit expanded #t)

Для получения и изменения значения в qt используйте атрибут value. В html интерфейсе часы будут работать только в браузерах с включенной поддержкой Javascript.