Flash using ActionScript libraries tutorial

Introduction

Learning goals

• Learn how to reuse example code that illustrate features of ActionScript libraries.
• Learn how to be able to import 3rd party packages by defining an ActionScript classpath.

Prerequisites

• Basic interactivity, i.e. some very limited ActionScript 3 coding experience. See for example the Flash button tutorial or the Flash component button tutorial and theFlash embedded movie clip tutorial.
• In addition, you also could start from "pure" Actionscript 3 coding (but we will provide no explanations here for flex style development...)

Environment

• Flash CS3

Moving on

• See the Flash tutorials.

Level and target population

• Beginners (but see the prerequisites)

Quality

• useable, but under progress.

To Do

• Other examples

There exist several free high quality ActionScript libraries available and that can be used by Flash designers that only possess very little programming skills.

Typical examples of such libraries are:

• Flash 3D libraries that allow a CS3 developer to create animated and interactive 3D scenes.
• Special purpose animation libraries like the FLiNT particle system that allows you to create stuff like fireworks and snowflakes.
• Tweening libraries like TweenLite that allow you to define sophisticated animations with a few method calls (instead of spending hours of drawing).
• Physics engines like Box2DFlashAS3

Flash libraries can come in several forms (see Flash formats and objects overview). In this short tutorial we will deal with

• .swc - compiled clips that include ActionScript code and other stuff
• .fla - Flash CS3/CS4 source code files
• .as - Action script code.

In this tutorial, we just will a short overview. If want to go through an example, either read the FliNT particle system introductory tutorial. FLiNT is a very useful library to create very cool animations with particles flying around or play around with the easier to use AS3 tweening platform.

List of libraries that are part of these Flash tutorials:

• FliNT particle system
• Flash Papervision3D tutorial
• AS3 tweening platform

Others:

• see Reusable AS components and libraries

Installing and using libraries overview

This is a short executive overview on using ActionScript libraries

To use external ActionScript libraries that you downloaded and installed, Flash must locate the external ActionScript files that contain the class definition. Usually, the list of folders in which Flash searches for class definitions is called the classpath for ActionScript 2.0 and the source path for ActionScript 3.0

You may set the source path either globally (for all your projects) or per *.fla file. You usually should adopt the later, even if it means some extra work.

Local source path:

Through File->Publish Settings; Flash Tab; Settings Tab; you can set the following ActionScript locations in Flash for a specific *.fla file:

• Source path: Defines the location of source ActionScript source files. Typically you would use this for libraries that you download as AS source code.
• Library path: “specifies the location of pre-compiled ActionScript code which resides in SWC files you have created. The FLA file that specifies this path loads every SWC file at the top level of this path and any other code resources that are specified within the SWC files themselves. If you use the Library path, be sure none of the compiled code in the SWC files is duplicated in uncompiled AS files in the Source path. The redundant code will slow down compilation of your SWF file.”. Typically, you would use the library path when you use *.swc code from major ActionScript libraries like PaperVision3D or the Greensock tweening libraries.
• External library path: specifies the location of SWC files that contain code used for compiler error definitions. This path can be used to load external code resources in SWC format so that the classes within them can be used at runtime. When you compile a SWF, the SWC files in the External Library path are not added to the SWF file, but the compiler verifies that they are in the locations you specified. The External Library path is most often used for runtime shared libraries. For more information about runtime shared libraries, see working with runtime shared assets
• Document class (also can be set in Document Property inspector). Used to associate a specific class with a document, i.e. typically used to compile an ActionScript program you write yourself.

Local source path (alternative option):

Alternatively (not recommended):

• Instead of defining the source path: You also could copy the com directories that include source to the directory where your *.fla file sits,
• Instead of defining a library path: Copy the *.swc file to the same directory of your *.fla file and add . to the library path.

Global source path:

Through Edit->Preferences->ActionScript 3.0 Settings you can set source pathes for all your projects:

• Source path
• Library path
• External library path

Setting source pathes

Below we reproduce the detailed explanations from Adobe's Set the location of ActionScript files (retrieved 17:37, 10 May 2010 (UTC)):

Set the source path for ActionScript 3.0

To set the document-level source path:

1. Select File -> Publish Settings, and click Flash.
2. Verify that ActionScript 3.0 is selected in the ActionScript Version pop‑up menu, and click Settings. Your Flash Player version must be set to Flash Player 9 or later to use ActionScript 3.0.
3. Specify the frame where the class definition should reside in the Export Classes in Frame text field.
4. Specify the Errors settings. You can select Strict Mode and Warnings Mode. Strict Mode reports compiler warnings as errors, which means that compilation will not succeed if those types of errors exist. Warnings Mode reports extra warnings that are useful for discovering incompatibilities when updating ActionScript 2.0 code to ActionScript 3.0.
5. (Optional) Select Stage to automatically declare stage instances.
6. Specify ActionScript 3.0 or ECMAScript as the dialect to use. ActionScript 3.0 is recommended.
7. To add paths to the source path list, do any of the following:
   • To add a folder to the source path, click the Source path tab and then click the Browse To Path button , browse to the folder to add, and click OK.
   • To add a new line to the Source path list, click the Add New Path button. Double-click the new line, type a relative or absolute path, and click OK.
   • To edit an existing Source path folder, select the path in the Source path list, click the Browse To Path button, browse to the folder to add, and click OK. Alternatively, double-click the path in the Source path list, type the desired path, and click OK.
   • To delete a folder from the source path, select the path in the Source path list and click the Remove From Path button .

To set the application-level source path:

1. Choose Edit Preferences (Windows) or Flash > Preferences (Macintosh) and click the ActionScript category.
2. Click the ActionScript 3.0 Settings button and add the path(s) to the Source path list.

Set the Library path for ActionScript 3.0 files

To set the document-level Library path, the procedure is similar to setting the Source path:

1. Choose File Publish Settings and click the Flash tab.
2. Make sure ActionScript 3.0 is specified in the Script menu and click Settings.
3. In the Advanced ActionScript 3.0 dialog box, click the Library path tab.
4. Add the library path to the Library path list. You can add folders or individual SWC files to the path list.

To set the Application-level Library path:

1. Choose Edit Preferences (Windows) or Flash > Preferences (Macintosh) and click the ActionScript category.
2. Click the ActionScript 3.0 Settings button and add the path(s) to the Library path list.

Set the External Library path for ActionScript 3.0 files

To set the document-level External Library path, the procedure is similar to setting the Source path:

1. Choose File Publish Settings and click the Flash tab.
2. Make sure ActionScript 3.0 is specified in the Script menu and click Settings.
3. In the Advanced ActionScript 3.0 dialog box, click the External Library path tab.
4. Add the library path to the External Library path list. You can add folders or individual SWC files to the path list.

To set the Application-level External Library path:

1. Choose Edit->Preferences (Windows) or Flash->Preferences (Macintosh) and click the ActionScript category.
2. Click the ActionScript 3.0 Settings button and add the path(s) to the External Library path list.

A note on classes and packages

All ActionScript code that you will import is defined with classes (see the Actionscript 3 tutorials if you really want to learn how programming works.). Theses classes can then be bundled together in so-called packages which allows to organize code into discrete groups that can be imported by other scripts.

In other words, if you want to use a class that is inside a package, you must import either the package or the specific class. “In general, import statements should be as specific as possible. If you plan to use only the SampleCode class from the samplespackage, you should import only the SampleCode class rather than the entire package to which it belongs. Importing entire packages may lead to unexpected name conflicts. You must also place the source code that defines the package or class within your classpath . The classpath is a user-defined list of local directory paths that determines where the compiler will search for imported packages and classes. The classpath is sometimes called the build path or source path” (Importing packages, retrieved 17:37, 10 May 2010 (UTC)).

Syntax:

import samples.*;

Example from the TweenMax engine of the AS3 tweening platform:

import com.greensock.*; 
import com.greensock.easing.*;

TweenMax.to(mc, 3, {bezier:[{x:277, y:174}, {x:300, y:345}], orientToBezier:true, ease:Bounce.easeOut});

For programmers (see the ActionScript 3 tutorials, to create your own packages:

package packageName {
   class someClassName { 
   } 
}

More information about packages can be found in Adobe's Packages and namespaces chapter in the Programming ActionScript 3.0 tutorial which is very technical.

ActionScript document classes

According to ActionScript publish settings, retrieved 17:37, 10 May 2010 (UTC):

When you use ActionScript 3.0, a SWF file may have a top-level class associated with it. This class is called the document class. When the SWF is loaded by Flash Player, an instance of this class is created to be the SWF file's top-level object. This object of a SWF file can be an instance of any custom class you choose.

For example, a SWF file that implements a calendar component can associate its top level with a Calendar class, with methods and properties appropriate to a calendar component. When the SWF is loaded, Flash Player creates an instance of this Calendar class.

1. Deselect all objects on the Stage and in the Timeline by clicking a blank area of the Stage. This displays the Document properties in the Property inspector.
2. Enter the filename of the ActionScript file for the class in the Document Class text box in the Property inspector. Do not include the .as filename extension.

Note: You can also enter the Document Class information in the Publish Settings dialog box.

Links

• ActionScript publish settings (Adobe Flash CS4)

• Sharing library assets (Adobe Flash CS4)

• Packages and namespaces (Adobe Flash CS4)