Overview of the Macromedia Flash JavaScript API

The ActionScript language lets you write scripts to perform actions in the Flash Player environment (that is, while a SWF file is playing). The Flash JavaScript API lets you write scripts to perform several actions in the Flash authoring environment (that is, while a user has the Flash program open). These scripts can be used to help streamline the authoring process. For example, you can write scripts to automate repetitive tasks, add custom tools to the Tools panel, or add timeline effects.

The Flash JavaScript API is designed to resemble the Macromedia Dreamweaver and Macromedia Fireworks JavaScript API (which were designed based on the Netscape JavaScript API). The Flash JavaScript API is based on a Document Object Model (DOM), which allows Flash documents to be accessed using JavaScript objects. The Flash JavaScript API includes all elements of the Netscape JavaScript API, plus the Flash DOM. These added objects and their methods and properties are described in this document. You can use any of the elements of the native JavaScript language in a Flash script, but only elements that make sense in the context of a Flash document will have an effect.

The JavaScript API also contains a number of methods that let you implement extensibility using a combination of JavaScript and custom C code. For more information, see Chapter 3, "C-Level Extensibility," on page 533.

The JavaScript interpreter in Flash is the Mozilla SpiderMonkey engine, version 1.5, which is available on the web at www.mozilla.org/js/spidermonkey/. SpiderMonkey is one of the two reference implementations of the JavaScript language developed by Mozilla.org. It is the same engine that is embedded in the Mozilla browser.

SpiderMonkey implements the core JavaScript language as defined in the ECMAScript (ECMA-262) edition 3 language specification and it is fully compliant with the specification. Only the browser-specific host objects, which are not part of the ECMA-262 specification, are not supported. Similarly, many JavaScript reference guides distinguish between core JavaScript and client-side (browser-related) JavaScript. Only core JavaScript applies to the Flash JavaScript interpreter.

Creating JSFL files

You can use Macromedia Flash 8 or your preferred text editor to write and edit Flash JavaScript (JSFL) files. If you use Flash, these files have a .jsfl extension by default.

You can also create a JSFL file by selecting commands in the History panel and then clicking the Save button in the History panel or selecting Save As Command from the options pop-up menu. The command (JSFL) file is saved in the Commands folder (see "Saving JSFL files" on page 7). You can then open the file and edit it the same as any other script file.

The History panel provides some other useful options as well. You can copy selected commands to the Clipboard, and you can view JavaScript commands that are generated while you are working in Flash.

To copy commands from the History panel to the Clipboard:

1. Select one or more commands in the History panel.

2. Do one of the following:

   • Click the Copy button.

   • Select Copy Steps from the options pop-up menu.

To view JavaScript commands in the History panel:

• Select View > JavaScript in Panel from the options pop-up menu.

Saving JSFL files

You can have JSFL scripts available within the Flash authoring environment by storing them in one of several folders within the Configuration folder. By default, the Configuration folder is in the following location:

• Windows 2000 or Windows XP:

  boot drive\Documents and Settings\user\Local Settings\Application Data\Macromedia\ Flash 8\language\Configuration\

• Mac OS X:

  Macintosh HD/Users/userName/Library/Application Support/Macromedia/Flash 8/language/Configuration/

To determine the location of the Configuration folder, use fl.configDirectory or fl.configURI.

Within the Configuration folder, the following folders can contain scripts that you can access in the authoring environment: Behaviors, Commands (for scripts that appear on the Commands menu), Effects (for timeline effects), JavaScript (for scripts used by Script Assist), Tools (for extensible tools in the Tools panel), and WindowSWF (for panels that appear in the Windows menu). This document focuses on scripts used for commands, effects, and tools.

If you edit a script in the Commands folder, the new script is immediately available in Flash. If you edit a script for an effect or extensible tool, you have to close and restart Flash, or else use the fl.reloadEffects() or fl.reloadTools() command. However, if you used a script to add an extensible tool to the Tools panel and you then edit the script, you must either remove and then add the tool to the Tools panel again, or else close and restart Flash for the revised tool to be available.

There are three locations where you can store command, effect, and tool files so they can be accessed in the authoring environment.

• For scripts that will appear as items in the Commands menu, save the JSFL file in the Commands folder in the following location:

  • Windows 2000 or Windows XP:

    boot drive\Documents and Settings\user\Local Settings\Application Data\Macromedia\ Flash 8\language\Configuration\Commands

  • Mac OS X:

    Macintosh HD/Users/userName/Library/Application Support/Macromedia/Flash 8/language/Configuration/Commands

• For scripts that will appear as extensible tools in the Tools panel, save the JSFL file in the Tools folder in the following location:

  • Windows 2000 or Windows XP:

    boot drive\Documents and Settings\user\Local Settings\Application Data\Macromedia\Flash 8\ language\Configuration\Tools

  • Mac OS X:

    Macintosh HD/Users/userName/Library/Application Support/Macromedia/Flash 8/language/Configuration/Tools

• For scripts that will appear as timeline effects in the Effects panel, save the JSFL file in the Effects folder in the following location:

  • Windows 2000 or Windows XP:

    boot drive\Documents and Settings\user\Local Settings\Application Data\Macromedia\Flash 8\ language\Configuration\Effects

  • Mac OS X:

    Macintosh HD/Users/userName/Library/Application Support/Macromedia/Flash 8/language/Configuration/Effects

If a JSFL file has other files that go with it, such as XML files, they should be stored in the same directory as the JSFL file.

Running JSFL files

There are several ways to run JSFL files. The most common ways are discussed in this section.

To run a script that is in the Commands folder, do one of the following:

• Select Commands > Script Name.

• Use a keyboard shortcut that you have assigned to the script. To assign a keyboard shortcut, use Edit > Keyboard Shortcuts and select Drawing Menu Commands from the Commands pop-up menu. Expand the Commands node in the menu tree to view a list of available scripts.

To run a command script that is not in the Commands folder, do one of the following:

• From the authoring environment, select Commands > Run Command, and then select the script to run.

• From within a script, use the fl.runScript() command.

• From the file system, double-click the script file.

To add a tool implemented in a JSFL file to the Tools panel:

1. Copy the JSFL file for the tool and any other associated files to the Tools folder (see "Saving JSFL files" on page 7).

2. Select Edit > Customize Tools Panel (Windows) or Flash > Customize Tools Panel (Macintosh).

3. Add the tool to the list of available tools.

4. Click OK.

You can add individual JavaScript API commands to ActionScript files by using the MMExecute() function, which is documented in the ActionScript 2.0 Language Reference. However, the MMExecute() function has an effect only when it is used in the context of a custom user-interface element, such as a component Property inspector, or a SWF panel within the authoring environment. Even if called from ActionScript, JavaScript API commands have no effect in Flash Player or outside the authoring environment.

To issue a command from an ActionScript script:

• Use the following syntax (you can concatenate several commands into one string):

  MMExecute(Javascript command string);

  
  

You can also run a script from the command line.

To run a script from the command line on Windows:

• Use the following syntax (add path information as required):

  "flash.exe" myTestFile.jsfl

  
  

To run a script from the command line on the Macintosh:

• Use the following syntax (add path information as required):

  osascript -e 'tell application "flash" to open alias "Mac OS   X:Users:user:myTestFile.jsfl" '

  
  

  The osascript command can also run AppleScript in a file. For example, you could put the following text in a file named myScript:

  tell application "flash"   open alias  "Mac OS X:Users:user:myTestFile.jsfl" end tell

  
  

  Then, to invoke the script, you would use this command:

  osascript myScript