Полный список методов взаимодействия Flash и внешних программ
Эта статья является переводом с английского и компиляцией нескольких документов из официального руководства Macromedia (ныне Adobe) по взаимодействию между JavaScript и Flash. В процессе написание текст был дополнен информаций из других источников. Причиной, по которой я выполнил перевод этого текст, послужил тот факт, что в русском Интернете мне не удалось найти полного и доступного для понимания документа на эту тему.
Приведенные в этой статье методы являются специфичными JavaScript-функциями для взаимодействия с Flash. Данные методы используются для того, чтобы послать JavaScript-запрос во Flash-клип. Каждый метод имеет имя и большинство методов имеют аргументы. Аргументы определяют как будет выполняться метод. По завершению некоторые методы возвращают значения, которые могут использоваться JavaScript.
Для того, чтобы можно было использовать методы взаимодействия JavaScript и Flash клипу, помещенному в html-страницу, необходимо присвоить имя. Для этого нужно указать имя в аттрибуте id тэга <object>, а также в аттрибутах id и name тэга <embed>. Имя может быть любым, но в рамках данной статьи будем считать, что клипу присовено имя movie. Кроме того в тэге<embed> нужно указать аттрибут swLiveConnect=true.
Пример присвоения имени клипу
<object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/
cabs/flash/swflash.cab#version=7,0,0,0" width="690" height="250" id="movie">
<param name="menu" value="false" />
<param name="bgcolor" value="#ffffff" />
<param name="quality" value="high" />
<param name="movie" value="movie.swf" />
<embed swLiveConnect=true src="movie.swf" menu="false" quality="high" bgcolor="#ffffff" width="690" height="250" name="movie" id="movie" type="application/x-shockwave-flash" pluginspage="http://www.macromedia.com/go/getflashplayer" />
</object>
Для обращения к клипу рекомендуется использвать следующую конструкцию:
var isInternetExplorer = navigator.appName.indexOf("Microsoft") != -1;
movie = isInternetExplorer ? document.all.movie : document.movie;
Следует добавить, что в Internet Explorer, описаные в этой статье методы, будут работать только на сервере. С локального диска отладить скрипты не получится. Учитываейте это при разработке собственных приложений.
Содержание
- Стандартные методы
- TellTarget методы
- Стандартные события
- FSCommand для автономного плеера
- Список всех свойств и соответсвующих им номеров
- Источники
Стандартные методы
GetVariable
Версия плагина (ActionX): 4 и выше
Синтаксис
GetVariable ( varName )
Описание
Возвращает значение переменной, определенной во Flash как varName. Возвращает null, если переменная не определена. Аргумент типа string.
Пример
var firstName = movie.GetVariable("FirstName");
var radioButtonValue = movie.GetVariable("/Form/RadioButton:Value");
GotoFrame
Версия плагина (ActionX): 2 и выше
Синтаксис
GotoFrame ( frameNumber )
Описание
Активирует кадр, определенный как frameNumber в текущем клипе. Если данные для запрошенного кадра недоступны, то плеер перейдет в последний доступный кадр и остановит воспроизведение, что может стать причиной неожиданого результата воспроизведения клипа. Используйте метод PercentLoaded(), чтобы определить загрузился ли клип настолько, чтобы вы могли вызвать метод GotoFrame() для нужного кадра.
Пример
movie.GotoFrame(24);
IsPlaying
Версия плагина (ActionX): 2 и выше
Синтаксис
IsPlaying ()
Описание
Возвращает true, если воспроизведение клипа уже началось.
Пример
if (movie.IsPlaying()) {
alert("movie is playing");
}
LoadMovie
Версия плагина (ActionX): 3 и выше
Синтаксис
LoadMovie ( layerNumber, url )
Описание
Загружает клип указанный как url в слой определенный как layerNumber. Тип аргументов: integer для layerNumber и string для url.
Пример
movie.LoadMovie(0, "mymovie.swf");
Pan
Версия плагина (ActionX): 2 и выше
Синтаксис
Pan ( x, y, mode )
Описание
Выполняет панорамирование увелеченного клипа в координаты, определнные как x и y. Используйте mode для того, чтобы установить указаны ли x и y в пикселях или в процентах от размера окна. Когда mode равен 0, координаты измеряются в пикселях; когда mode равен 1, координаты измеряются в процентах от размеров окна. Панорамирование не выполняется за пределами увеличенного клипа. Тип всех аргументов integer.
Примеры
Этот пример выполняет панорамирование на 50% вправо и на 50% вниз:
movie.Pan(50, 50, 1);
Этот пример выполняет панорамирование на -25 пикселов влево и на -25 пикселов вверх:
movie.Pan(-25, -25, 0);
PercentLoaded
Версия плагина (ActionX): 2 и выше
Синтаксис
PercentLoaded ()
Описание
Возвращает процент загрузки клипа на текущий момент. Возможные значения от 0 до 100.
Пример
if (movie.PercentLoaded() == 100) {
loaded = true;
}
Play
Версия плагина (ActionX): 2 и выше
Синтаксис
Play ()
Описание
Начинает воспроизведение клипа.
Пример
movie.Play();
Rewind
Версия плагина (ActionX): 2 и выше
Синтаксис
Rewind ()
Описание
Выполняет переход в первый кадр клипа.
Примечание: В некоторых (но не во всех) случаях это означает повтороное воспроизведение клипа.
Пример
movie.Rewind();
SetVariable
Версия плагина (ActionX): 4 и выше
Синтаксис
SetVariable ( variableName, value )
Описание
Присваивает переменной Flash определенной как variableName значение определнное как value. Тип обоих аргументов string.
Пример
movie.SetVariable("/Form:UserName", "John Smith");
SetZoomRect
Версия плагина (ActionX): 2 и выше
Синтаксис
SetZoomRect ( left, top, right, bottom )
Описание
Увеличивает прямоугольную область клипа. Единцы измерения координат — твипы (twips). В одном дюйме 1440 твипов. Для вычисления размеров прямоугольной области в твипах во Flash установите в качестве единиц измерения линеек пункты (Points) и умножьте полученные кординаты на 20 (с учётом того факта, что в одном дюйме 72 пункта). Тип всех аргументов integer.
Пример
Этот пример увеличивает прямоугольную область размером 200 x 200 пикселов, расположенную в левом верхнем углу клипа:
var pointsToTwips = 20;
movie.SetZoomRect(0, 0, 200 * pointsToTwips, 200 * pointsToTwips);
StopPlay
Версия плагина (ActionX): 2 и выше
Синтаксис
StopPlay ()
Описание
Останавливает воспроизведение клипа.
Пример
movie.StopPlay();
TotalFrames
Версия плагина (ActionX): 2 и выше
Синтаксис
TotalFrames ()
Описание
Возвращает общее количество кадров в клипе.
Пример
var totalFrames = movie.TotalFrames();
Zoom
Версия плагина (ActionX): 2 и выше
Синтаксис
Zoom ( percent )
Описание
Изменяет масштаб в сообтветствии с относительным коэффициентом масштабирования определенным как percent. Zoom(50) удвоит размеры обектов клипа. Zoom(200) уменьшит размеры обектов клипа на половину. Zoom(0) вернет масштаб 100%. Тип аргумента integer.
Пример
movie.Zoom(50);
TellTarget методы
Методы TellTarget позволяют обращаться к отдельным объектам клипа. Синтаксис указания пути аналогичен синтаксису ActionScript.
TCallFrame
Версия плагина (ActionX): 4 и выше
Синтаксис
TCallFrame ( target, frameNumber )
Описание
В объекте, определенном как target, вызывается код в каде определенном как frameNumber.
Пример
Это пример запускает код в пятом кадре в корне клипа:
movie.TCallFrame("/", 4);
TCallLabel
Версия плагина (ActionX): 4 и выше
Синтаксис
TCallLabel ( target, label )
Описание
В объекте, определенном как target, вызывается код в каде определенном меткой кадра label. Тип всех аргументов string.
Пример
Это пример запускает код в кадре с меткой HandleScriptNotify в корне клипа:
movie.TCallLabel("/", "HandleScriptNotify");
TCurrentFrame
Версия плагина (ActionX): 3 и выше
Синтаксис
TCurrentFrame ( target )
Описание
Возвращает номер текущего кадра в объекте, определенном как target. Номера кадров считаются от нуля. То есть первый по порядку кадр клипа счтается нулевым, второй - первым, и т. д. Тип аргумента string.
Пример
var currentFrame = movie.TCurrentFrame("/MovieClip");
TCurrentLabel
Версия плагина (ActionX): 3 и выше
Синтаксис
TCurrentLabel ( target )
Описание
Возвращает метку текущего кадра в объекте, определенном как target. Если текущий кадр не имеет метки, то возвращает пустую строку (string). Тип аргумента string.
Пример
var currentLabel = movie.TCurrentLabel("/MovieClip");
TGetProperty
Версия плагина (ActionX): 4 и выше
Синтаксис
TGetProperty ( target, property )
Описание
Для объекта, определенном как target, возвращает строку (string), указвающую значение свойства, определенного как property. В качестве property указывается целое число (номер свойства) соответсвующее желаемому свойству. Для того чтобы определить какой норме какому свойству соответсвует см. Список всех свойств и соответсвующих им номеров.
Пример
var nameIndex = 13;
var name = movie.TGetProperty("/", nameIndex);
TGetPropertyAsNumber
Версия плагина (ActionX): 4 и выше
Синтаксис
TGetPropertyAsNumber ( target, property )
Описание
Для объекта, определенном как target, возвращает число, указвающее значение свойства, определенного как property. В качестве property указывается целое число (номер свойства) соответсвующее желаемому свойству. Для того чтобы определить какой норме какому свойству соответсвует см. Список всех свойств и соответсвующих им номеров.
Пример
var framesLoadedIndex = 12;
var name = movie.TGetPropertyAsNumber("/", framesLoadedIndex);
TGotoFrame
Версия плагина (ActionX): 3 и выше
Синтаксис
TGotoFrame ( target, frameNumber )
Описание
В объекте, определенном как target, осуществляется переход к кадру, опредленному как frameNumber. Тип аргумента target — string. Тип аргумента frameNumber — integer.
Пример
movie.TGotoFrame("/MovieClip", 2);
TGotoLabel
Версия плагина (ActionX): 3 и выше
Синтаксис
TGotoLabel ( target, label )
Описание
В объекте, определенном как target, осуществляется переход к кадру, имеющему метку, опредленную как label. Тип обеих аргументов string.
Пример
movie.TGotoLabel("/MovieClip", "MyLabel");
TPlay
Версия плагина (ActionX): 3 и выше
Синтаксис
TPlay ( target )
Описание
Начинает воспроизведение объекта, определенного как target. Тип аргумента string.
Пример
movie.TPlay("/MovieClip");
TSetProperty
Версия плагина (ActionX): 4 и выше
Синтаксис
TSetProperty ( target, property, value )
Описание
Для объекта, определенном как target, устанавливает новое значение свойства, определенного как property. Новое значение свойства определяется как value. В качестве property указывается целое число (номер свойства) соответсвующее желаемому свойству. Для того чтобы определить какой норме какому свойству соответсвует см. Список всех свойств и соответсвующих им номеров.
Пример
var visibilityIndex = 7;
var nameIndex = 13;
movie.TSetProperty("/MovieClip", visibilityIndex, 1);
movie.TSetProperty("/MovieClip", nameIndex, "NewName");
TStopPlay
Версия плагина (ActionX): 3 и выше
Синтаксис
TStopPlay ( target )
Описание
Останавливает воспроизведение объекта, определенного как target. Тип аргумента string.
Пример
movie.TStopPlay("/MovieClipToStop");
Стандартные события
OnProgress
Версия плагина (ActionX): 2 и выше
Синтаксис
OnProgress ( percent )
Описание
Генериться в процесе скачивания клипа. Тип аргумента integer.
OnReadyStateChange
Версия плагина (ActionX): 2 и выше
Синтаксис
В общем случаи
OnReadyStateChange ( stage )
В коде HTML
<object onreadystatechange="handler" ... >
В JavaScript
movie.onreadystatechange = handler
Описание
Применительно к использованию в браузере не является специфичной функцией для взаимодействия Flash и JavaScript. Событие OnReadyStateChange доступно и для других элементов html-страницы. Поддерживается Internet Explorer начиная с 3.02 для <Hn> и namespace, начиная с 4.0 для <LINK>, <OBJECT>, <SCRIPT> и document, начиная с 5.0 для остальных элементов и начиная с 5.5 для <IFRAME>. Когда в состоянии клипа происходят изменения вызывается обработчик событий handler. Возможные состояния клипа приведены в Таблице 1. Тип аргумента integer.
| Описание сосотояния клипа | Состояние |
|---|---|
| Возникает перед началом загрузки | loading |
| Не инициализирован | uninitialized |
| В процессе загрузки | loaded |
| В процессе взаимодействия с пользователем | interactive |
| Полностью загружен | complete |
Примечание: В теории идея выглядит очень красиво, но на практике всё не так просто. Браузер Internet Explorer не вызывает это событие для flash-клипа, хотя вызывает например для document. Тем не менее привожу примеры того, как это могло быть реализовано.
Пример
Это абсолютно работоспособный пример, который задает обработчик события OnReadyStateChange для document.
document.onreadystatechange = function () {
alert ("Ready state: " + document.readyState);
}
Это пример, который мог бы работать:
function CheckState () {
alert ("Ready state: " + movie.readyState);
}
<object onreadystatechange="CheckState()" id="movie" ...>
FSCommand
Версия плагина (ActionX): 2 и выше
Синтаксис
FSCommand ( command, args )
Описание
Генериться в тот момент, когда в клипе вызывается метод FSCommand. Два параметра передаются из Flash в JavaScript: имя команды, определенное как command, и аргументы команды, определнные как args. В принципе параметры абсолютно равноценны и могуть быть использованы как угодно. Тип обеих аргументов string.
Пример
<SCRIPT LANGUAGE="JavaScript">
function movie_DoFSCommand(command,args) {
alert ("Команда: " + command + "; Аргументы: " + args);
}
</SCRIPT>
Для корректной работы данного метода в Internet Explorer необходимо вместе с кодом на JavaScript использовать следующий код на VBScript:
<SCRIPT LANGUAGE=VBScript>
Sub movie_FSCommand(ByVal command,ByVal args)
call movie_DoFSCommand (command,args)
end sub
</SCRIPT>
FSCommand для автономного плеера
При воспроизведении клипа в автономном плеере (проекторе) Flash взаимодействует не с JavaScript, а с операционной системой.
quit
Версия плагина (ActionX): 2 и выше
Синтаксис
fscommand ("quit")
Описание
С помощью этой команды плеер закрывает себя.
fullscreen
Версия плагина (ActionX): 2 и выше
Синтаксис
fscommand ("fullscreen", value)
Описание
Когда аргумент value равен true плеер разворачивается на весь экран, когда value равен false — возвращается к нормальному виду.
Пример
fscommand ("fullscreen", true);
allowscale
Версия плагина (ActionX): 2 и выше
Синтаксис
fscommand ("allowscale", value)
Описание
Когда аргумент value равен true масштаб клипа меняется при изменение размеров окна плеера, когда value равен false масштаб клипа отсается неизменным.
Пример
fscommand ("allowscale", false);
showmenu
Версия плагина (ActionX): 2 и выше
Синтаксис
fscommand ("showmenu", value)
Описание
Если аргумент value равен true, то контекстное меню отображется в полном виде. Если value равен false, то в контекстном меню скрываются все пункты кроме пунктов Settings... и About Flash Player.
Пример
fscommand ("showmenu", false);
exec
Версия плагина (ActionX): 2 и выше
Синтаксис
fscommand ("exec", path)
Описание
Запускает внешнее приложение, расположенное по пути опредленному как path.
Примеры
Этот пример демонстрирует запуск калькулятора Windows.
fscommand ("exec","calc.exe");
Для того чтобы исполнить системную команду, состоящую из нескольких "слов" (с пробелами), то разделителем между этими словами должен быть не пробел, а символ табуляции. Его можно вставить с помощью специальной комбинации \t .
Это пример иллюстрирует выполнение команды dir c:\:
fscommand ("exec","command.com\t/c\tdir\tc:\\");
trapallkeys
Версия плагина (ActionX): 2 и выше
Синтаксис
fscommand ("trapallkeys", value)
Описание
Когда аргумент value равен true разрешает перехват всех клавиатурных комбинаций.
Пример
fscommand ("trapallkeys", true);
Список всех свойств и соответсвующих им номеров
В приведенной ниже таблице показаны свойства, к которым можно получить доступ из браузера с помощью JavaScript. Свойства, отмеченные в колонке Чтение могут быть прочитаны с помощью методов TGetProperty и TGetPropertyAsNumber. Свойтсва, отмеченные в колонке Запись могут быть изменены с помощью метода TSetProperty. Номер свойства соответсвующий каждому свойству указывается при использовании методов TGetProperty, TGetPropertyAsNumber или TSetProperty для того, чтобы указать к какому именно свойства обращаются вызываемые методы.
| Свойство | Номер свойства | Чтение | Запись |
|---|---|---|---|
| _x | 0 | Да | Да |
| _y | 1 | Да | Да |
| _xscale | 2 | Да | Да |
| _yscale | 3 | Да | Да |
| _currentframe | 4 | Да | |
| _totalframes | 5 | Да | |
| _alpha | 6 | Да | Да |
| _visibility | 7 | Да | Да |
| _width | 8 | Да | |
| _height | 9 | Да | |
| _rotation | 10 | Да | Да |
| _target | 11 | Да | |
| _framesloaded | 12 | Да | |
| _name | 13 | Да | Да |
| _droptarget | 14 | Да | |
| _url | 15 | Да |
В приведенной ниже таблице показаны глобальные свойства.
| Свойство | Номер свойства | Чтение | Запись |
|---|---|---|---|
| _highquality | 16 | Да | Да |
| _focusrect | 17 | Да | Да |
| _soundbuftime | 18 | Да | Да |
Источники
Flash Methods
http://www.adobe.com/support/flash/publishexport/scriptingwithflash/scriptingwithflash_03.html
Getting and setting properties
http://www.adobe.com/support/flash/publishexport/scriptingwithflash/scriptingwithflash_04.html
Учебник по Flash 5
http://vbalex.narod.ru/book/26.html
Справочник web-языков
http://pages.plotinka.ru/~elizavet/spravka/index-120.htm
onreadystatechange Event
http://www.nedcomp.nl/support/origdocs/xml4/extracted/xml_evt_0a9g.aspx
