Средства документирования во Flash MX

Во Флэш МХ встроена неплохая система онлайн-документации. Лучшее свойство этой системы -

простота модификации. Программисту, написавшему свой компонент не составит труда сделать

по нему справочный файл для дизайнеров (доступный прямо в среде разработки). Именно этим мы

сейчас и займемся.
Установка онлайн-документации
Среда разработки Flash MX предоставляет несколько возможностей помощи в работе с

кодом ActionScript. Это References, контекстные подсказки, подсвечивание элементов кода,

а так же специфические возможности редактирования в режимах Normal и Expert. Информация,

необходимая для работы этих инструментов хранится в xml-файлах. Чтобы она стала доступна

в среде разработки, достаточно просто поместить эти файлы в специальное место. Это можно

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

от операционной системы; находится эта папка в пользовательском профиле (profile), там, где

хранятся данные установленных программ. Вот несколько примеров для самых распространенных

систем (вместо User подставьте имя конкретного пользователя):
Windows 2000 and XP
C:\Documents and Settings\User\Application Data\Macromedia\Flash
MX\Configuration\ActionsPanel\CustomActions

Windows 98 and ME
C:\Windows\Application Data\Macromedia\Flash
MX\Configuration\ActionsPanel\CustomActions

Windows NT
C:\WinNT\Profiles\User\Application Data\Macromedia\Flash
MX\Configuration\ActionsPanel\CustomActions

MAC OS X
Hard Drive:Users:Library:Application
Support:Macromedia:FlashMX:Configuration:ActionsPanel:CustomActions:

Mac OS 9.x (multi-user)
Hard Drive:Users:User:Documents:Macromedia
:FlashMX:Configuration:ActionsPanel:CustomActions:

Установить эти файлы можно также из ActionScript, с помощью метода install объекта CustomActions ).
liftRef_xml = new XML();
liftRef_xml.load("lift.xml");
liftRef_xml.onLoad = function(){
instSuccess =
CustomActions.install("lift",liftRef_xml.toString());
trace(instSuccess);
trace(CustomActions.list());
}

Этот код устанавливает References и подсказки к классу lift, информация о которых находится

в файле lift.xml, а также выводит список установленных компонентов документации (CustomActions.list()).

После выполнения этого кода в окне Output должен появиться следующий текст
true
UIComponents,UIComponents2,UIComponents2Ref,lift

Строчка "true" - содержимое переменной instSuccess - то, что возвращает метод CustomActions.install в

случае успешного выполнения, следующая строчка - список уже установленных компонентов

, среди которых появился lift. В панелях Actions и References должны появиться новые папки

(информация о них содержится в файле lift.xml).
В следующих параграфах будет рассмотрен формат xml-файлов, необходимых для работы инстр

ументов онлайн-документации. А пока мы рассмотрим один важный вопрос: можно ли состави

ть документацию на русском языке? Точнее, будет ли она корректно отображаться? Мы вправе

этого ожидать, зная, что среда Флэш МХ ориентирована на использование Unicode. И действите

льно, если файлы справки, сделанные, скажем, в Notepad, сохранять в Unicode, а не в ANSI, Ф

лэш сможет их правильно отобразить. Правда, поначалу фа

йлы могут показываться некорректно; в этом случае придется (кроме сохранения файлов в Unico

de) сделать еще одну вещь. В системном реестре откройте ключ HKEY_LOCAL_MACHINE\SY

STEM\CurrentControlSet\Control\Nls\CodePage, найдите значение 1252 и установите соответству

ющую ему строчку данных в c_1251.nls. Те, кто много работал, например, с Adobe Photoshop,

хорошо знают этот фокус. Для большей надежности можно проделать ту же операцию с анало

гичными ключами, расп оложенными не в CurrentControlSet, а в ControlSet001, ControlSet002 и т

.д.; впрочем, обычно это не требуется. После этого достаточно закрыть среду Флэш и снова ее

запустить; теперь (если только русская локаль у вас настроена правильно) все должно работать.

Как сделать Reference

Корневым элементом xml-документа, распознаваемого средой разработки Flash MX, явля
О специфических для тега <string> атрибутах text, type и object мы поговорим в следующих параграфах.

Текст References

Тексты References содержатся в тегах <reference>. Этот тег имеет атрибут path, в нем

указывается путь в дереве папок, по которому должен быть доступен данный текст.

Сам текст содержится внутри тега, в формате html. Из html-тегов поддерживаются <p>,

<b>, <I>, <br> и <a>. В отличие от html, все теги обязательно должны быть закрыты. Д

ля форматирования текста рекомендуется пользоваться предопределенными стилями (у

казываются в атрибуте class тега <p>). Это стили titleStyle (заголовок, один на каждый о

бъект), subTtle - подзаголовок и codeStyle - используется для примеров кода. В атрибуте h

ref тега <a>, как и в html, указывается путь к документу, на который ведет ссылка, в следую

щем виде:"reference:[путь]".
Вприведен xml-исходник описания одного из методов класса Lift. Напоказано, как это опи

сание выглядит в панели References.

<reference path="Lift/Methods/goto">

   <p class="titleStyle">Lift.goto</p>

   <p class="subTitle">Доступность</p>

   <p>Flash Player 6.</p>

   <p class="subTitle">Использование</p>

   <p class="codeStyle"><i>my_lift.</i>goto(<i>floor</i>)</p>

   <p class="subTitle">Параметры</p>

   <p><i>floor</i> - целое число. Номер этажа.</p>

   <p class="subTitle">Возвращает</p>

   <p> Номер этажа, на котором оказался лифт </p>

   <p class="subTitle">Описание</p>

   <p>Отправляет лифт на заданный этаж.</p>

   <p class="subTitle">См. также</p>

   <p class="codeStyle">

   <a href="reference:Lift">Класс Lift</a><br/>

   <a href="reference:Lift/Properties/minFloor">Lift.minFloor</a>

   <br/>

   <a href="reference:Lift/Properties/maxFloor">Lift.maxFloor</a>

   <br/>

   </p>

</reference>

Что именно писать в References - это, конечно, решает программист. Но лучше п
ридерживаться стиля, в котором написаны References для встроенных объектов 
Flash MX. А именно, там должны содержаться следующие пункты: 

1. Доступность - версия плеера, начиная с которой данный объект нормально работает.

2. Использование - синтаксис вызова, если речь идет о методе, создание объекgisterClass тут как тут.

Контекстные подсказки

Чтобы получить подсказку в среде Flash MX, не обязательно запускать Help или смотреть

References. Некоторые подсказки могут появиться непосредственно при наборе кода. Например,

если набрать "my_mc.", то рядом с курсором появится список полей и методов класса MovieClip,

из него можно выбрать элемент, который вставится в код. Такие же подсказки можно сделать и

для собственных классов
Эти подсказки описываются также в xml-файле, за них отвечает тег <codehints>. Тег не имеет

атрибутов, но может содержать теги <codehint> и <typeinfo>. В тегах <codehint> описаны паттерны

кода вроде "on" или "onClipEvent". При написании классов новых таких паттернов не возникает,

так что этот тег нам не понадобится. А вот в тегах <typeinfo> как раз и содержится информация о

контекстных подсказках вроде тех, что показаны на.
Тег <typeinfo> имеет атрибуты pattern и object.
pattern - часть кода, по которой выдается подсказка. Как правило, для этого используются суффиксы,

начинающиеся с символа "_".
object - объект, список полей которого выдается в подсказке.
Например:

<typeinfo pattern="*_lift" object="Lift"/>

Для того чтобы поле попало в список, выпадающий по данному паттерну кода, в теге

string>, описывающем данный метод, должен быть атрибут object, значение которого

совпадает со значением атрибута object соответствующего тега typeinfo.
Напоминаем, что для получения подсказок по встроенным объектам, нужно пользоваться

следующими паттернами кода:

На паттерны "_level*", "_parent" и "_root" также выдаются подсказки MovieClip'а.
Кроме списка методов и полей, для каждого метода можно получить подсказку по синтаксису его вызова.
За это отвечает атрибут text тега <string>.

Подсвечивание кода

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

заведомо узнаваемые интерпретатором слова выделяются цветом. А для работы во Flash MX,

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

к несуществующей переменной (если вы ему это нечаянно скомандовали), это особенно важно.
Разными цветами в редакторе выделяются следующие объекты: строки, комментарии, ключевые

слова и идентификаторы. На то, что определяется как строки и комментарии, мы повлиять не

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

пользователю поля и методы наших классов было бы полезно.
За это отвечает тег <colorsyntax>. Он не имеет атрибутов, содержит теги <identifier> (и <keyword>,

но они нам не понадобятся). Каждый тег <identifier> имеет атрибут text, значение которого и задает

то слово, которое надо раскрасить. Например:

<colorsyntax>

   <identifier text="Lift"/>

   <identifier text=".goto"/>

   <identifier text=".minFloor"/>

   <identifier text=".maxFloor"/>

</colorsyntax>

Описания для Normal mode

Кроме обычного режима (Expert mode), редактор FlashMX допускает еще один режим,

Normal mode, в котором не позволяется вставить в код ничего "лишнего". Пользователь

, выбравший для редактирования кода Normal mode, даже не имеет возможности набир

ать текст в основном окне - только в специально отведенных для этого полях (надо заме

тить, что до пятой версии Flash только такая возможность и существ

овала).
Для того чтобы и в Normal mode была возможность пользоваться вашими классами, их

необходимо описать в уже обсуждавшихся ранее тегах <string>. Сейчас нам важны атриб

уты text, tiptext и type. Атрибуты text и tiptext используются как в Expert-mode, так и в Normal

mode. В Normal mode значение атрибута tiptext выводится в верхней строке окна Actions.

Атрибут text, который в Expert mode отвечает за удобную, но необязательную подсказку, в

Normal становится жизненной необходимостью. Именно то, что указано в атрибуте text, в

Normal mode и вставится в текст программы, п ользователю же будет разрешено ввести

только то, что находится между значками "%". Если метод допускает больше одного варианта

вызова, можно пользоваться атрибутами text2, text3 и т. д.
Атрибут type используется только для редактирования в Normal mode. Если ему присвоено

значение "procedure", то пользователю будет предоставлен шаблон для вызова метода - то

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

Если речь идет о полях, которые не являются методами, атрибут type можно не указывать.
В приведено описание метода goto класса Lift, а напоказано добавление этого метода в код

при редактировании в Normal mode.

<string name="goto" tiptext="Метод, отправляет лифт на заданный этаж"

text=".goto(% floor %);" text2=".goto();"type="procedure"

                        object="Lift" version="6" />