Обозреватель

Observer

четверг, 17 января 2008 г.

Вся правда о ASDoc комментариях. Часть первая. Создание ASDoc комментариев. //Выбраны основные положения

Оригинал. LIFE.Flash.

А вместе с ASDoc пришел новый набор правил, с которыми я хотел бы вас познакомить. Правил довольно много. Формат ASDoc это, модифицированный под ActionScript, формат javadocs.

Элементы, поддерживаемые в ASDoc

ASDoc поддерживает следующие элементы, встречающиеся в ActionScript файле:

  • многострочные комментарии (multi-line comments)
  • ASDoc теги
  • определения class и interface
  • свойства
  • методы
  • set/get методы
  • теги метаданных (metadata tags)

Включение ASDoc комментариев

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

Пример ASDoc комментария:

/**
* Comment text.
*
* @tag Tag text.
*/

Для того, что бы добавить дополнительный параграф используйте стандартный HTML-тег <p></p>.

Вставлять комментарий необходимо до объявления класса, интерфейса, конструктора или тега метаданных.

ASDoc игнорирует комментарии, вставленные в тело функции. Признается только один комментарий, который описывает функцию до ее объявления.
Также, распространенной ошибкой, является вставка комментария описывающий класс, не над непосредственным объявлением класса, а над import. Избегайте данной ошибки, так как ASDoc просто проигнорирует такой комментарий.

Основное описание начинается сразу после разделителя /** и продолжается до раздела тегов. Первое предложение основного описания, должно содержать краткое, но полное описание сущности комментируемого (класса, функции, метода, свойства и т.д.). Основное описание заканчивается сразу после первой точки или разделителя строки (\r).
Секция тегов, начинается сразу после первого тега, который объявляется символом @ в начале линии. С помощью тегов создаются отдельные заголовки, например такие как –

  • param (параметры),
  • return (результаты возврата функции), а также
  • see (смотреть, т.е. своеобразная ссылка, на другую функцию, документацию которой необходимо прочитать).
Вы можете создавать неограниченное число тегов; некоторые теги могут повторяться, например, такие как @param и @see, но (!) другие нет.

ASDoc генерирует документацию всех публичных элементов ActionScript-класса, даже если вы игнорируете комментарии. Если вы хотите что бы ASDoc игнорировал какой-то элемент, вы можете использовать тег @private. Тег @private может содержать дополнительный пояснительный текст.
Тегом @private, вы можете запретить генерацию не только приватных элементов класса, но и всего класса в частности (так как документация генерируется и для всех публичных классов тоже). Для этого необходимо включить тег @private в описание класса.

Несколько правил парсинга (синтаксического анализа) ASDoc комментариев:

  • Все элементы кода, находящиеся после ASDoc комментария, копируются в генерируемый файл документации.
  • Если у ASDoc комментарий отсутствует, то в элемент кода генерируется без всякой документации.
  • Если в ASDoc комментарии встречается тег @private, ASDoc игнорирует это элемент кода (если эта функция не изменена в конфигурации ASDoc).
    В ASDoc однострочный комментарий // и многострочный комментарий, начинающийся с одной звездочкой /*, игнорируются.
  • Форматированные участки (<p>, <b>, <i> и т.п.) встречающиеся в ASDoc комментариях допускаются. Но учтите, некоторые элементы должны вводиться в виде кодовых эквивалентах HTML. Например, знак больше (>) или меньше (<) должны быть прописаны как < и >. Или например амперсанд “&” должен быть прописан как &.
  • Не забывайте, что теги HTML обязаны наследовать правила форматирования формата XML, т.е. если вы открываете тег, то он должен быть обязательно закрыт. Например тег <li> должен быть закрыт тегом </li>.

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

Геттер/сеттер методы обрабатываются ASDoc отдельно, так как эти элементы используются как свойства, хотя на самом деле ими не являются. Поэтому ASDoc создает для каждого геттер/сеттер метода документацию, аналогичную документации свойств.
Обычно для геттер/сеттер метода создается единый комментарий, с одним описанием. А сеттер комментируется тегом @private. Это рекомендуется делать, так как обычно геттер объявляется раньше сеттера.

ASDoc может выдать ошибку, если ваш исходный файл содержит символы, имеющие кодировку не UTF-8. В этом случае, при генерации документации, ASDoc вернет номер строки, где встречаются некорректные символы.

Обработка метаданных

Для определения элементов компонента, Flex использует теги метаданных. ASDoc поддерживает теги метаданных и обращается к ним также, как к методам и свойствам.Поддерживаемые теги метаданных в ASDoc:

  • [Event(name=" eventName ", type=" eventType ")]
  • [Style(name=" styleName ", type=" type ", format=" format ", inherit="yesno")]
  • [Effect(name=" effectName ", event=" triggeringEventName ")]
  • [Bindable("event="eventname")]
  • [DefaultProperty(" name ")]
  • [Exclude(name=" elementName ", kind="propertymethodeventstyleeffect")]

Разработчики применяют теги метаданных, чтобы документировать события, стили, эффекты, применяемые в классе. Метаданные, бывают в виде [Event args], [Style args], и [Effect args] и обычно создаются сразу после объявления класса.

/** * Defines the name style. */
[Style "name"]

Для событий и эффектов, тег метаданных включает в себя имя класса, непосредственно связанного с событием или эффектом. Приведем пример из класса mx.controls.Button:

/**
* ... this event is dispatched repeatedly as long as the button stays down.
*
* @eventType mx.events.FlexEvent.BUTTON_DOWN
*/
[Event(name="buttonDown", <strong>type="mx.events.FlexEvent"</strong>)]

Для такого комментария, ASDoc сделает следующее:

  • В конечном файле, класса mx.controls.Button, ASDoc создаст ссылку на класс события (mx.events.FlexEvent), определенного в аргументе type.
  • Также, ASDoc копирует описание константы, значение которой возвращает Event.type класса Button. В ASDoc вы можете использовать тег @eventType, для определения константы. В данном примере, ASDoc копирует описание константы mx.events.FlexEvent.BUTTON_DOWN класса Button. Константа mx.events.FlexEvent.BUTTON_DOWN определяет значение объекта, связанного с событием.

В ASDoc комментарии, для константы mx.events.FlexEvent.BUTTON_DOWN вы должны вставить в таблицу возвращаемые значения (bubbles, cancelable, target, и currentTarget) свойства класса Event.

Для примера, рекомендуется посмотреть весь класс mx.controls.Button и классы mx.events.FlexEvent.
Для каждого метода или свойства, вы должны определять, какие события отправляются (или как говорят “диспатчатся”) методу или свойству. Для этого необходимо использовать тег @event описывая каждый метод или свойство. Тег @event имеет следующий формат:

@event eventName eventObjectClassName [description]

среда, 16 января 2008 г.

Опасные FlashVars //Советы относительно Flashvars

Оригинал. Блог одиноко стоящего игрока вспышки.
Flashvars долго казались мне самой безобидной субстанцией.Однако и у них есть пара опасных моментов.

  • Не забываем, что все данные, переданные через flashvars - это String.То есть если нужно передать число или булеву переменную - будьте добры, используйте приведение типов. И лучше руками, не полагаясь на автомат.
  • Недавно обнаруженная грабля.Допустим у нас есть флешка, на основном таймлайне которой мы импортируем пакет flash.filters.* . Или не импортируем на таймлайн, но создаем переменную некоего класса SomeClass, в коде которого мы как раз и производим этот импорт.Так вот ежели мы передадим flashvar flash=kill_my_package, то мы наглухо убъем доступ к пакету flash. Точно так же можно убить пакеты mx, ru, com и все необходимое )). Однако если мы будем импортировать пакеты на временной линейке любого другого мувиКлипа, лежащего на основной линейке, то все будет работать.

А вывод прост: следим за именами переменных, откуда бы они не приходили. Потому как и во вложенном клипе можно убить доступ к пакету, просто объявив в нем переменную

var flash:Boolean = false;

вторник, 15 января 2008 г.

SmartFont //Класс загрузки внешних библиотек шрифтов

Оригинал. Блог одиноко стоящего игрока вспышки.

Над проблемой загрузки внешних библиотек шрифтов не трудился, наверное, только ленивый.
Вариантов решения проблемы много. Коммерческие, не коммерческие, рабочие, не рабочие, удобные и неудобные.
Вашему вниманию мой класс SmartFont.На сайте поддержки описаны все телодвижения, здесь же упомяну только общий ход использования:

var my_font:SmartFont = new SmartFont();
my_font.load(“someFont.swf”);
my_font.onLoad = function():Void {
trace(“Шрифт: “+this._font+” готов к использованию”);
}

понедельник, 14 января 2008 г.

С чем же едят H.264? //О поддержке видео-кодека H.264 flash-плеером

Оригинал. Блог одиноко стоящего игрока вспышки.

Итак, о поддержке видео-кодека H.264 мы услышали, но как с ним работать в условиях флеш-плеера? Да ничего особенного, как оказалось. Все тот же Джастин Эврертт-Чёрч, все разложил по полочкам.Даже если ваш проект скомпилирован под 7-й плеер, все равно вы можете работать с этим кодеком. Все дело именно в новом плеере.
Раньше у нас было два кодека on2vp6 и SorensonSpark. Оба кодека использовались в контейнере FLV. Новый кодек пакуется в контейнер mp4 и это жесткое требование - мп4 и все тут. К слову сказать - это общепринятая практика. Многие mov, 3gp и m4v файлы пакуют видео через кодек h.264 именно в контейнер mp4.Если же мы имеем фал другой организации - тогда, конечно, флеш плеер ничего сним сделать не сможет.Если вы сами пакуете свои видео файлы - то тут все понятно - правильно пакуем, и все будет хорошо. Если вам попался чей то видео файл - то самый простой способ проверить его совместимость с плеером - просто проиграть его в нем )

ScrollRect vs setMask //Без комментариев.

Оргигнал. Блог одиноко стоящего игрока вспышки.

Если нужно применить к клипу прямоугольную маску, вместо MovieClip.setMask(mc:MovieClip) лучше воспользоваться свойством scrollRect (доступно от 8-й версии и выше).
Плюс в производительности на лицо. Более того - под такой “маской” не пропадают системные и не-внедренные шрифты.
Использование предельно просто:

import flash.geom.Rectangle;
var maskRect:Rectangle = new Rectangle(x,y,width,height);
my_mc.scrollRect = maskRect;

С такой “маской” удобно делать также и скроллеры (собственно название выдает). Достаточно поменять значение x, y для Rectangle, и визуально мы видим смещение контента мувиКлипа.

Прелоадер для ‘img’ //Управление изображениями, подгружаемыми в Textfield

Оригинал. Блог одиноко стоящего игрока вспышки.

TextField - субстанция крайне интересная, взбаломошная и мистическая.Обуздание оной подчас превращается в подвиг Геракла.Несколько статей о TеxtField я обязательно размещу на страницах этого блога.
Многие знают, что в текстовое поле с подключенным html можно грузить картинки и флешки, а также вставлять символы из библиотеки.Но вот вопрос - а можно ли взаимодействовать с этими объектами? Например возможен ли прелоадер?ДА и очень просто. Фактически тег img создает внутри тексатового поля новый MovieClip. Если в html-коде прописан id для IMG, то будет создан клип именно с таким instance name. И обращаться к этому клипу можно через текстовое поле. К примеру если в текстовое поле my_txt внедряется картинка

[img src="http://murejib.wordpress.com/wp-admin/someIMG" id="img" /]

То мы можем обратиться к ней my_txt.img
Но что если у нас есть html-текст с img без id, и таких картинок много, а нам необходимо сделать скроллер для текстового поля. Пока картинки не загружены мы с большой долей вероятности получим неверную высоту поля.Есть простой способ - нам нужно просто завести массив для учета встроенных картинок

var htmlIMG:Array = [];

И пройтись по текстовому полю циклом for…in, помня, что картинки - это объекты типа MovieClip.

for (var mc in my_txt) {
if (typeof(my_txt[mc]) == “movieclip”) {
trace (”found IMG: “+my_txt[mc]);
htmlIMG.push(my_txt[mc])
}
}

Теперь у нас есть массив, в которые занесены ссылки на все клипы.А дальше - прелоадер должен собрать все загруженные байты этих клипов и все тотальные байты этих же клипов. Суммируем, делим, получаем процент. По завершению загрузки - проверяем высоту поля, и приделываем наш бесценный скроллер.

expRandom. //Управление распределением вероятности

Оригинал. Блог одиноко стоящего игрока вспышки.

Иногда бывает нужно, чтобы случайное число с большей вероятностью выпадало ближе к минимальным, или максимальным значениям.
Простой пример - Слот машина.Бонусные символы должны выпадать гораздо реже обычных символов.Существует масса способов реализовать такой рандом, о них, к примеру была речь на форуме flash-mx
Более того мне необходимо, что бы числа возвращались в жестко заданном диапазоне.Немного мозгового скрипа дало мне вот такую функцию.

function expoRandom(range:Number,w:Number):Number {
w = Math.max(w,1);
w = Math.min(w,709);
return Math.log(1+Math.random()*(Math.exp(w)-1))*(range/w);
}

В функцию передается два параметра - собственно диапазон, и, не знаю как это правильно обозвать, степень разброса. От это степени зависит насколько сильно выпадающие значения будут тесниться к максимальному краю. Чем больше степень, тем ближе к краю.
В функцию вставлена небольшая проверка - чтобы ширина не была меньше 1 (в этом случае мы получим обычный рандом) и не была больше 709 (в этом случае выражение Math.exp(w) даст нам infinity). Их собсвенно можно убрать, дабы не забивать процессор лишней работой.
Вся магия тут завязана на простой принцип - есть график логарифма. Мы берем случайное число по оси X и находим его логарифм по оси Y. Немного корректируем под наш диапазон - и результат на лице.

Вот к примеру такой:http://bbexp.ru/blog/_stuff/random.html

Анимация статичного растра. Имитация 3D. //Анимационный прием

Оригинал. Блог одиноко стоящего игрока вспышки.

Если у нас есть кусок растра, который во чтобы то ни стало надо как то анимировать - можно воспользоваться увлекательной нарезкой персонажа на куски )Принцип метода достаточно прост.
Имея представление о рельефе анимируемой фигуры, разбиваем растр на несколько клипов, фигурно отсекая лишние части на каждом уровне. Очень неплохо таким способом можно анимировать лица, морды, руки и т.д.
Первый пример наглядно иллюстрирует суть метода.

Смотреть

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

суббота, 12 января 2008 г.

Первая жертва

Идея этого субблога родилась при просмотре блога со странным названием "Блог одиноко стоящего игрока вспышки". При просмотре первых нескольких постов мне сразу захотелось "не забыть" изложенные в них идеи и куда-нибудь их отложить для быстрого их нахождения и применения в будущем. Но основной блог загружать награбленным не хочется - да и не этично как-то.
И вот позвольте представить - "Чужая тетрадь". Название навеяно воспоминаниями о школьно-студенческих временах, когда нередко тетрадь друга выручала на контрольной или экзамене. Когда бесценная тетрадь с лекциями какого-нибудь отличника бережно передавалась из рук в руки, ксерилась и переписывалась незадолго до сессии...
Итак, начало списыванию положено, да не осудят меня мои коллеги.