Средства документирования во 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 (пример 12.1).

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, Флэш сможет их правильно отобразить. Правда, поначалу файлы могут показываться некорректно; в этом случае придется (кроме сохранения файлов в Unicode) сделать еще одну вещь. В системном реестре откройте ключ HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\CodePage, найдите значение 1252 и установите соответствующую ему строчку данных в c_1251.nls. Те, кто много работал, например, с Adobe Photoshop, хорошо знают этот фокус. Для большей надежности можно проделать ту же операцию с аналогичными ключами, расп оложенными не в CurrentControlSet, а в ControlSet001, ControlSet002 и т.д.; впрочем, обычно это не требуется. После этого достаточно закрыть среду Флэш и снова ее запустить; теперь (если только русская локаль у вас настроена правильно) все должно работать.

Как сделать Reference

Корневым элементом xml-документа, распознаваемого средой разработки Flash MX, является тег <customactions>. Он может содержать теги <actionspanel>, <colorsyntax>, <codehints> и <reference>.

<actionspanel> содержит описание дерева папок в панели Actions и оглавлении References. В <colorsyntax> перечисляются элементы кода, которые должны выделяться другим цветом в редакторе. <codehints> определяют контекстные подсказки. Теги <reference> содержат подробные описания элементов, перечисленных в <actionspanel>. Остановимся на каждом из этих тегов подробнее.

<actionspanel>.

Этот тег атрибутов не имеет, может содержать теги <folder> и <string>. Тег <folder> в свою очередь так же может содержать теги <folder> и <string>. Тег <string> вложенных тегов не имеет. Вся информация, которую несут теги <folder> или <string>, содержится в их атрибутах.

Тег <folder> отвечает за группу элементов (например, на рис. 12.2 это папка Lift, а так же содержащиеся в ней папки Methods и Properties ).

Многие атрибуты являются общими для тегов <folder> и <string>. Первый из них - name, его значение - это имя папки или элемента, отображаемое в панели Actions и оглавлении References. Атрибут id использует для гиперссылок в References (подробнее см. ниже). Чтобы не путаться, значения атрибутов id и name обычно делают одинаковыми. Атрибут tiptext содержит краткую информацию о папке или объекте, которая отображается в виде tooltip (всплывающей подсказки) в панели Actions или оглавлении References (рис. 12.3).

Кроме того, у тега <folder> есть булевский атрибут sort, по умолчанию true. Если sort установить равным false, то содержимое папки не будет сортироваться по алфавиту, а будет выведено именно в том порядке, в каком оно описано в xml-файле.

Атрибут version (число) указывает на номер версии плеера, начиная с которой можно использовать данный объект. Если в настройках публикации выставлена версия плеера ниже заданной атрибутом version, в панели Actions данная строчка будет подсвечена желтым, чтобы указатьn пользователю, что в данной версии плеера объект не работает. Если вы используете собственные классы, вам необходима версия плеера не ниже 6. Этот атрибут может быть как у тега <folder>, так и у тега <string>.

О специфических для тега <string> атрибутах text, type и object мы поговорим в следующих параграфах.

Текст References

Тексты References содержатся в тегах <reference>. Этот тег имеет атрибут path, в нем указывается путь в дереве папок, по которому должен быть доступен данный текст. Сам текст содержится внутри тега, в формате html. Из html-тегов поддерживаются <p>, <b>, <I>, <br> и <a>. В отличие от html, все теги обязательно должны быть закрыты. Для форматирования текста рекомендуется пользоваться предопределенными стилями (указываются в атрибуте class тега <p> ). Это стили titleStyle (заголовок, один на каждый объект), subTtle - подзаголовок и codeStyle - используется для примеров кода. В атрибуте href тега <a>, как и в html, указывается путь к документу, на который ведет ссылка, в следующем виде:" reference:[путь] ".

В примере 12.2 приведен xml-исходник описания одного из методов класса Lift. На рисунке 12.4 показано, как это описание выглядит в панели 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. А именно, там должны содержаться следующие пункты:

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

(рис 12.4) Пример описания в References

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

Что возвращает метод. (Вероятно, вы заметили, что в документации от Macromedia в подпункте Returns в подавляющем большинстве случаев написано Nothing, в то время как в подпункте Description явно сказано о том, что метод что-то возвращает. Это скорее всего ошибка, которую повторять не стоит.)

Описание с примерами кода. Что должно быть в описании, лучше всего знает создатель описываемой программы. Но не следует забывать и о тех, кто эти описания будет читать. Чтобы все возможности ваших объектов были эффективно использованы, нужно описать их (и объекты, и возможности) как можно более подробно и понятно. При написании References стоит временно отбросить убеждение " copy / paste - это плохо". References - не программа, а человек - не интерпретатор, и он не будет читать все подряд. (К сожалению, если вы подумываете использовать XML entities как альтернативу copy / paste, вынуждены вас разочаровать: они не поддерживаются системой онлайн-документации Флэш МХ). Если у вас есть несколько почти идентичных методов (например getMinFloor и getMaxFloor ) и их описания практически совпадают, лучше все-таки давать максимально п олное описание каждому объекту - скорее всего, прочитано будет что-то одно, и вы никогда не угадаете, что именно. С другой стороны, если для понимания работы данного объекта нужна какая-то информация, напрямую к нему не относящаяся, чтобы не загромождать окно, лучше расположить ее там, где она более уместна, но в тексте описания обязательно дать на нее ссылку.

Ссылки на похожие объекты. Оптимальный вариант - 3-4 ссылки на объекты, которые действительно могут понадобиться читающим это описание. Например, в описании метода MovieClip.attachMovie содержатся ссылки на MovieClip.removeMovieClip, MovieClip.unloadMovie, Object.registerClass. Что вполне логично: если человек подгружает клип из библиотеки, то ему, может быть, захочется его тем или иным способом удалить. Да и вполне резонный вопрос: "А почему я клип подгрузил, а мои методы не работают?" еще не успевает возникнуть, как Object.registerClass тут как тут.

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

Чтобы получить подсказку в среде Flash MX, не обязательно запускать Help или смотреть References. Некоторые подсказки могут появиться непосредственно при наборе кода. Например, если набрать " my_mc.", то рядом с курсором появится список полей и методов класса MovieClip, из него можно выбрать элемент, который вставится в код. Такие же подсказки можно сделать и для собственных классов (рис. 12.5).

Эти подсказки описываются также в xml-файле, за них отвечает тег <codehints>. Тег не имеет атрибутов, но может содержать теги <codehint> и <typeinfo>. В тегах <codehint> описаны паттерны кода вроде " on " или " onClipEvent ". При написании классов новых таких паттернов не возникает, так что этот тег нам не понадобится. А вот в тегах <typeinfo> как раз и содержится информация о контекстных подсказках вроде тех, что показаны на рис 12.5.

Тег <typeinfo> имеет атрибуты pattern и object.

pattern - часть кода, по которой выдается подсказка. Как правило, для этого используются суффиксы, начинающиеся с символа " _ ".

object - объект, список полей которого выдается в подсказке.

Например:

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

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

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

На паттерны " _level* ", " _parent " и " _root " также выдаются подсказки MovieClip 'а.

Кроме списка методов и полей, для каждого метода можно получить подсказку по синтаксису его вызова (рис 12.6).

За это отвечает атрибут 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 (рис. 12.7), в котором не позволяется вставить в код ничего "лишнего". Пользователь, выбравший для редактирования кода Normal mode, даже не имеет возможности набирать текст в основном окне - только в специально отведенных для этого полях (надо заметить, что до пятой версии Flash только такая возможность и существовала).

Для того чтобы и в Normal mode была возможность пользоваться вашими классами, их необходимо описать в уже обсуждавшихся ранее тегах <string>. Сейчас нам важны атрибуты text, tiptext и type. Атрибуты text и tiptext используются как в Expert-mode, так и в Normal mode. В Normal mode значение атрибута tiptext выводится в верхней строке окна Actions (см. рис. 12.7). Атрибут text, который в Expert mode отвечает за удобную, но необязательную подсказку, в Normal становится жизненной необходимостью. Именно то, что указано в атрибуте text, в Normal mode и вставится в текст программы, п ользователю же будет разрешено ввести только то, что находится между значками " % ". Если метод допускает больше одного варианта вызова, можно пользоваться атрибутами text2, text3 и т. д.

Атрибут type используется только для редактирования в Normal mode. Если ему присвоено значение " procedure ", то пользователю будет предоставлен шаблон для вызова метода - то есть, его попросят указать объект, у которого этот метод вызывается, и перечислить аргументы. Если речь идет о полях, которые не являются методами, атрибут type можно не указывать.

В примере 12.4 приведено описание метода goto класса Lift, а на рис.12.8 показано добавление этого метода в код при редактировании в Normal mode.

<string name="goto" tiptext="Метод, отправляет лифт на заданный этаж"
text=".goto(% floor %);" text2=".goto();"type="procedure"
                        object="Lift" version="6" />