Оглавление

Структура проекта
  Файлы и каталоги входящие в поставку
  Файлы скачиваемые отдельно
  Файлы и каталоги создаваемые в процессе работы
Использование build-скрипта
  Определенные цели
Автоматическое обращение шагов типа step
Использование SaveLoadDialog
Использование SmartTokenizer
Автоматическая проверка автоматов
Использование переменных
Важные замечания

Об ошибках сообщайте по адресу kgeorgiy@rain.ifmo.ru

Структура проекта

Файлы и каталоги входящие в поставку

docs/ Документация по Vizi
  readme.html Этот файл
  WhatsNew.html Что уже сделано
  ToDo.txt Что еще нужно сделать
meta/ Файлы необходимые для работы Vizi
  scripts Содержит build файл и xsl скрипты
  vizi-<version>.jar Билд текущей версии Vizi
projects/ Проекты, входящие в поставку
  FindMaximum/ Визуализатор алгоритма нахождения максимума (пример)
  vizi/ Исходные коды Vizi
ant.bat Запускает build-скрипт
build.properties Конфигурация build-скрипта в строчке project= укажите путь к свойствам проекта (исходно — к проекту FindMaximum).

Файлы скачиваемые отдельно

meta/bin/ Apache Ant (http://ant.apache.org).
Если Ant находится в другом месте, должна быть установлена переменная окружения ANT_HOME.
meta/classes-1.1.8.jar Java-классы от JDK v.1.1.8 используются для проверки визуализатора на совместимость.

Файлы и каталоги создаваемые в процессе работы

build/ Создается при построении проекта. Содержит автоматически сгенерированные файлы.
  jars/ Содержит откомпилированные классы и сконвертированные .property файлы.
  properties/ Содержит автоматически создаваемые .property файлы.
  temp/ Содержит временные файлы.
deploy/ Содержит автоматически сгенерированные HTML и cmd файлы для проектов на русском и английском языка и jar файлы для Vizi и визуализатора.
  vizi-<version>.jar Запакованный Vizi.
  <имя визуализатора>.jar Запакованный визуализатор.
  <имя визуализатора>_*.html HTML с визуализатором на соответсвующем языке.
  <имя визуализатора>_*.cmd Скрипт запуска визуализатора из командной строки.

Использование build-скрипта

Для запуска build-скрипта используется файл ant.bat с параметром, определяющим что требуется сделать. По умолчанию используется цель all.

Определенные цели

all Генерирует исходники автомата, файлы сообщения, компилирует проект, создает .jar и .html файлы.
Если в каталоге проекта находится файл classes-1.1.8.jar, то при компиляции осущетсвляется проверка на использование только методов и классов определенных в jdk 1.1.8.
clean Удаляет автоматически созданные каталоги.
jars компилирует проект и создает jar-файлы с визуализатором.
htmls Создает html-файлы для запуска визуализатора.
cmds Создает командные файлы для запуска визуализатора.
description Создает документацию к параметрам визуализатора.
check Создает командный файл для автоматической проверки автомата.
api-docs Компилирует java-doc комеентарии исходный текстов Vizi.
vizi Компилирует Vizi.

Автоматическое обращение шагов типа step

Для автоматического обращения шагов типа <step>. Треуется записать их с использование тега <action> вместо тэга <direct>.

Все присваивания переменным модели, записываются в обратимом виде:
  @<имя переменной> @= <выражение>
либо
  @<имя переменной>[<индекс>] @= <выражение>

Например:
  @max @= @a[@i];
  @i @= @i + 1; // Вместо @i++;
  @a[@i] @= @i;
  @a.b[@z[i][j]] @= @q[i][j];

Для присваиваний, осуществленных в теге <action> будет сгенирирован код их обращающий.

ПРИМЕЧАНИЕ: Присваивания не переменным модели нельзя записывать указанным образом.

ПРИМЕЧАНИЕ: В одном шаге нельзя одновременно использовать <action> и <direct> или <action> и <reverse>.

Использование SaveLoadDialog

SaveLoadDialog позволяет унифицировать окна сохраниения/восстановления состояния визуализатора. При этом он определяет возможность работы с файлами и буфером обмена и отражает соответствующие элементы интерфейса.

Для использования SaveLoadDialog вы создаете класс унаследованный от него и определяющий метод load. Метод load может возвращать логическое значение или бросать исключение. Если метод вернул "true", то SaveLoadDialog закрывается. Если метод бросил исключение, то сообщения этого исключения отображается в строке комментария, что позволяет генерировать сообщение в месте обнаружения ошибки.

Для SaveLoadDialog определены следующие свойства:
comment - комментарий отображаемый в строке комментария.
content - текущее содержимое.
initialContent - исходной содержимое (используется при нажатии на кнопку "вернуть".

При конфигурации доступны следующие параметры:
SaveLoadDialog  
  -CommentPane-lines Высота области комментария в строках
  -columns Исходное количество столбцов в области ввода
  -rows Исходное количество строк в области ввода

Использование SmartTokenizer

SmartTokenizer позволяет в удобном виде разбирать данные полученые от SaveLoadDialog. Он позволяет легко читать числа (целые и вещественные) и строчки. При этом, выводятся локализованные сообщения об ошибках. Так же возможна проверка на окончение ввода. При разборе игнорируются комментарии (как /* */ так и //). При заключении строки в кавычки она считывается как одно слово.

SmartTokenizer удобно использовать непосредственно в методе load SaveLoadDialog, так как при этом практически не придется делать обработку ошибок.

Автоматическая проверка автоматов

В Vizi входит автоматический проверяльщик автоматов на правильность обращения.

Для использования проверяльщика запустивть build-скрипт с параметром check. При этом, в каталоге deploy будет создан файл вида Check<имя визуализатора>.cmd. Этот при запуске получившегося файла указыватся размер (уровень) шага проверки. Проверяльщик прогоняет визуализатор до всех шагов указанного уровня и проверяет правильность обращения.

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

Если при проверке вы получаете NullPointerException, то скорее всего это означает, что переменная апплета используется не только для рисования, что не правильно.

Использование переменных

Начиная с версии 0.4 было введено разделение переменных на глобальные и локальные, а соответствующая поддержка введена в Vizi. Объявление переменных в модели данных поддерживается в целях обеспечения обратной совместимости, но их использование не рекомендуется.

Глобальные переменные определяются в описании алгоритма (<algorithm>), а не в модели данных (<data>) как раньше. Глобальные переменные доступны во всех автоматах, если в них не объявлена локальная переменная с тем же именем.

Локальные переменные определяются в описании автомате (<auto>), и доступны внутри только этого автомата.

Для обращения к переменным используется синтаксис
  @<имя переменной>
На пример:
  @max @= @a[@i];
при этом осуществляется обратимое присваивание переменной max значения i-го элемента массива a. Имя переменной, хранящей модель данных не используется в явном виде, а подставляется автоматически.

Для обращения к локальным переменным автоматов в процедуре toString введен синтаксис
  @<имя автомата>@<имя переменной>
На пример:
  buffer.append(@Main@i);
при этом осуществляется добавление к буфферу значения локальной переменной i автомата Main.

Для доступа к переменным модели из кода визуализатора используется синтаксис
  <модель>.<имя переменной>
для глобальных переменных и
  <модель>.<имя автомата>_<имя переменной>
для локальных переменных. На пример:
  data.max = 0;
  System.out.println(data.Main_i);

Важные замечания

  1. Обращение к экземпляру апплета должно происходить только из кода рисования (тега <draw>).
  2. Все стили фигур (ShapeStyle) нужно получать из конфигурации, а не пытаться создать в визуализаторе.
  3. Присваивания не переменным модели нельзя записывать в обратимом виде (см. Автоматическое обращение шагов типа step).
  4. В одном шаге нельзя одновременно использовать <action> и <direct> или <action> и <reverse> (см. Автоматическое обращение шагов типа step).