Интерфейс

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

Формы

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

Пример правильного описания для 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")

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

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

• Метки полей и заголовки должны начинаться с заглавной буквы.
• Если метка и поле находятся в одной строке, то метка должна заканчиваться символом двоеточия “:».
• Заголовки групп, включая заголовки 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" /> <!-- невидимое поле --> =====сheckbox===== Данный элемент предназначен для представления атрибута логического типа. Метка к checkbox должна идти после галочки и начинаться с заглавной буквы. Пример для qt:
(checkbox text “Label for checkbox”)
Для получения/изменения значения пользуйтесь атрибутом ##value##. Пример для html:
<input type="checkbox"/>Label for checkbox
Обратите внимание на написание тега в стиле xml, а не html. Пример работы в бакенде на shell:

Функция ##write_bool_param## принимает два параметра - имя и значение. В качестве значения допустимы любые варианты: y, yes, on, true (в любом регистре). Функция ##test_bool## применяется для "считывания" значения параметра, независимым от представления в протоколе виде. =====button====== Данный элемент предназначен для представления активных действий с формой. * Текст кнопок должен начинаться с заглавной буквы * Если кнопка открывает дополнительное диалоговое окно, то текст кнопки должен заканчиватья многоточием "..." * Ни один диалог модуля не должен содержать кнопки "Выход" Пример для qt:
(button text “Button name”)
Пример для html:
<input type="submit" class="btn" name="somename" value="Button name"/>
Обратите внимание на использование класса btn и на написание тега в стиле xml, а не html. =====combobox/listbox/select===== В самом простом случае данные элементы представляют атрибут типа перечисление (enum), то есть обеспечивают выбор одного варианта из числа возможных. Сombobox - более компактное представление чем Listbox, но одновременно выдно только один вариант, чтобы просмотреть остальные - надо вызвать выпадающий список. Список вариантов предоставляет бакенд (вызываемый с action list). Параметр ##enumref## - адрес к которому надо обращаться к бакенду за списком. Пример для qt:
(combobox enumref «/x11/avail_resolution») ;;компактное представление списка
(listbox enumref «/x11/avail_driver») ;; развёрнутое представление списка
Текущий выбранный вариант - параметр ##value##. Пример для html:
<select name="item1" enumref="/x11/avail_resolution"/> <!-- компактное представление списка >
<select name="item1" size="10" enumref="/x11/avail_driver"/> <! развёрнутое представление списка -->
Размер списка в строках - параметр ##size##. Обратите внимание на написание тега в стиле xml, а не html. Пример бакенда на shell:
...

...
Функция write_enum_item принимает два параметра: * вариант - то ключевое имя, которым пользуется бакенд * название варианта (необязательно) - то описание, которое будет выведено пользователю (возможно с переводом) Если функция вызвана без параметра, то она начинает со стандартного ввода строки с одним или более значениями, разделённых стандартным разделителем (переменная IFS). Первое и второе значение интерпретируются также: вариант и его название. =====checklistbox===== Также как и listbox представляет атрибут перечислимого типа, но уже с возможностью множественного выбора. Для заполнения списка используется тот же параметр ##enumref##. Для "массового" выделения бакенд должен выводить список имён, в бакенд результат возвращается также в виде списка . Список представляется в виде строки с разделителем ";", например "a;b;c;d". Пример для qt:
(checklistbox enumref «/dovecot/avail_mechanisms»)
Текущий набор выделенных элементов - параметр ##value##. Пример для html:
<table class="alterator-checklistbox" enumref="/dovecot/avail_mechanisms" name="mechanisms" />
=====edit===== Представляет атрибут строкового типа. Пример для qt:
(edit)
Для изменения и получения значения служит атрибут ##value##. Пример для html:
<input type="text" class="text" name="name1"/>
Пример бакенда на shell:
...

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