Установка онлайн-документации

Среда разработки Flash MX предоставляет несколько возможностей помощи в работе с кодом ActionScript. Это References, контекстные подсказки, подсвечивание элементов кода, а так же специфические возможности редактирования в режимах Normal и Expert. Информация, необходимая для работы этих инструментов хранится в xml-файлах. Чтобы она стала доступна в среде разработки, достаточно просто поместить эти файлы в специальное место. Это можно сделать вручную. Местоположение папки, в которую должны быть помещены файлы, зависит от операционной системы; находится эта папка в пользовательском профиле (profile), там, где хранятся данные установленных программ. Вот несколько примеров для самых распространенных систем (вместо User подставьте имя конкретного пользователя):

Windows 2000 and XP

Windows 98 and ME

Windows NT

MAC OS X

Mac OS 9.x (multi-user)

Установить эти файлы можно также из ActionScript, с помощью метода install объекта CustomActions (пример 12.1).

Рис. 12.1.  Методы объекта CustomActions

Этот код устанавливает References и подсказки к классу lift, информация о которых находится в файле lift.xml, а также выводит список установленных компонентов документации (CustomActions.list()). После выполнения этого кода в окне Output должен появиться следующий текст

Строчка "true" - содержимое переменной instSuccess - то, что возвращает метод CustomActions.install в случае успешного выполнения, следующая строчка - список уже установленных компонентов, среди которых появился lift. В панелях Actions и References должны появиться новые папки (информация о них содержится в файле lift.xml).

Рис. 12.2.  Установленный компонент в панели Actions или References

В следующих параграфах будет рассмотрен формат 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).

Рис. 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.

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

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

   
   Рис. 12.4.  Пример описания в References

2. Использование - синтаксис вызова, если речь идет о методе, создание объекта класса, и т. п. Если метод вызывается с аргументами, их лучше описать в отдельном подпункте.
3. Что возвращает метод. (Вероятно, вы заметили, что в документации от Macromedia в подпункте Returns в подавляющем большинстве случаев написано Nothing, в то время как в подпункте Description явно сказано о том, что метод что-то возвращает. Это скорее всего ошибка, которую повторять не стоит.)
4. Описание с примерами кода. Что должно быть в описании, лучше всего знает создатель описываемой программы. Но не следует забывать и о тех, кто эти описания будет читать. Чтобы все возможности ваших объектов были эффективно использованы, нужно описать их (и объекты, и возможности) как можно более подробно и понятно. При написании References стоит временно отбросить убеждение "copy / paste - это плохо". References - не программа, а человек - не интерпретатор, и он не будет читать все подряд. (К сожалению, если вы подумываете использовать XML entities как альтернативу copy / paste, вынуждены вас разочаровать: они не поддерживаются системой онлайн-документации Флэш МХ). Если у вас есть несколько почти идентичных методов (например getMinFloor и getMaxFloor) и их описания практически совпадают, лучше все-таки давать максимально п олное описание каждому объекту - скорее всего, прочитано будет что-то одно, и вы никогда не угадаете, что именно. С другой стороны, если для понимания работы данного объекта нужна какая-то информация, напрямую к нему не относящаяся, чтобы не загромождать окно, лучше расположить ее там, где она более уместна, но в тексте описания обязательно дать на нее ссылку.
5. Ссылки на похожие объекты. Оптимальный вариант - 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.

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

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

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

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

Например:

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

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

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

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

Рис. 12.6.  Контекстные подсказки по вызову метода

За это отвечает атрибут text тега <string>.

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

Вероятность допустить синтаксическую ошибку заметно снижается, если "правильно" набранные, заведомо узнаваемые интерпретатором слова выделяются цветом. А для работы во Flash MX, который, ни слова не сказав, честно попытается вызвать несуществующий метод или обратиться к несуществующей переменной (если вы ему это нечаянно скомандовали), это особенно важно.

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

За это отвечает тег <colorsyntax>. Он не имеет атрибутов, содержит теги <identifier> (и <keyword>, но они нам не понадобятся). Каждый тег <identifier> имеет атрибут text, значение которого и задает то слово, которое надо раскрасить. Например:

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

Кроме обычного режима (Expert mode), редактор FlashMX допускает еще один режим, Normal mode (рис. 12.7), в котором не позволяется вставить в код ничего "лишнего". Пользователь, выбравший для редактирования кода Normal mode, даже не имеет возможности набирать текст в основном окне - только в специально отведенных для этого полях (надо заметить, что до пятой версии Flash только такая возможность и существовала).

Рис. 12.7.  Normal mode

Для того чтобы и в 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.

Рис. 12.8.  Редактирование в Normal mode