Using Code Examples

This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you're reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O'Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product's documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: "Flash Hacks, by Sham Bhangal. Copyright 2004 O'Reilly Media, Inc., 0-596-00645-4."

If you feel your use of code examples falls outside fair use or the preceding permission, feel free to contact us at permissions@oreilly.com.

Getting the Code Examples Working

The most common reason for being unable to get a code example to work (assuming you haven't made any typos) is a failure to set up the Flash file according to the instructions. Reread the surrounding text and follow the steps carefully. Be sure to place the code where it belongs (usually in the first frame of the actions layer or in an external .as file). Be sure you've set the compiler version to ActionScript 2.0 under FilePublish SettingsFlashActionScript Version.

Any code example that accesses movie clips, buttons, or text fields via ActionScript won't work unless you set the item's instance name properly. To set the instance name for a movie clip, button, or text field, select it on stage and enter the instance name on the left side of the Properties panel (WindowProperties) where you see the placeholder "<Instance Name>".

Another common source of problems is failure to set a symbol's linkage identifier properly, as is necessary when accessing Library symbols from ActionScript. To set the linkage identifier for a symbol, check the Export for Actionscript and Export in First Frame checkboxes in the Symbol Properties or Linkage Properties dialog box. (These are accessible by selecting a symbol in the Library (WindowLibrary) and choosing either Properties or Linkage from the Library panel's pop-up Options menu.) Then enter the identifier in the field labeled Identifier (which isn't active until Export for ActionScript is checked).

Read the instructions carefully to make sure you haven't confused a movie clip instance name with a symbol linkage identifier.

If you still can't get it working, download the examples from this book's web site, contact O'Reilly book support, or check the book's errata page. If all else fails, get a tutorial book on Flash or ask an experienced Flasher for help.

Many of the longer examples and sample files can be downloaded from this book's web page at http://examples.oreilly.com/flashhks.

ActionScript 1.0 Versus ActionScript 2.0

Many of the hacks presented in this book are written in ActionScript 2.0, which requires the Flash MX 2004 or Flash MX Professional 2004 authoring environment. You can use either of these authoring tools (see http://www.macromedia.com/software/flash/productinfo/features/comparison for a comparison of the two) because we don't use any features that are exclusive to the Professional edition. To make sure the examples compile, you should set the ActionScript Version to ActionScript 2.0 under FilePublish SettingsFlash. All examples have been tested in Flash Player 7.

Where noted, ActionScript 2.0 class definitions must be placed in external .as files. For example, the custom Transform class [Hack #10] must be placed in an external plain-text file named Transform.as (both the capitalization of the name and the .as extension are mandatory). You can create and edit such a file in Flash MX Professional 2004 if you select FileNewActionScript File. If using Flash MX 2004, you'll need an external text editor [Hack #74] .

We can't give a full course on object-oriented programming (OOP) and ActionScript 2.0 here, although we do try to provide pointers throughout the book. For many more details on ActionScript 2.0 classes and object-oriented development, see Essential ActionScript 2.0 by Colin Moock (O'Reilly).

Most examples can also be exported in Flash Player 6 format from Flash MX 2004 (standard or Professional edition), by setting the Export format to Flash Player 6 under FilePublish SettingsFlash.

However, methods that are new to Flash MX 2004 and Flash Player 7 won't work if you are exporting to Flash Player 6 format. For example, where we use MovieClip.getNextHighestDepth( ) in the code examples, you'll have to substitute it with a unique depth or it won't work in Flash Player 6.

The previous version of the Flash authoring tool, Flash MX, does not support ActionScript 2.0. However, many of the hacks and example code will work in Flash MX. If you have Flash MX and want to try out an ActionScript 2.0 hack, you can convert most of the examples to ActionScript 1.0 by simply removing the ActionScript 2.0 datatyping as shown next.

For example, here is the ActionScript 2.0 code using datatypes (shown in bold):

// ActionScript 2.0 with datatypes

// Requires Flash MX 2004 authoring environment

// configured to compile ActionScript 2.0

function myFunction(x:Number):Number {

  var y:Number = 2 * x;

  return y;

}

var myString:String = "hello";

var myClip:MovieClip = this.createEmptyMovieClip("myClip", 0);

var double:Number = myFunction(2);

trace(double);

And here is the ActionScript 1.0 version without datatypes:

// ActionScript 1.0 (untyped)

// Works in Flash MX authoring environment (and later)

function myFunction(x) {

  var y = 2 * x;

  return y;

}

var myString = "hello";

var myClip = this.createEmptyMovieClip("myClip", 0);

var double = myFunction(2);

trace(double);

This book uses a lot of timeline-based code, which, although it is not necessarily a best practice, is supported for both ActionScript 1.0 and ActionScript 2.0. We made this choice because most of the examples don't lend themselves readily to custom ActionScript 2.0 classes. This also makes the examples easier to follow and implement in both Flash MX and Flash MX 2004.

Some of the class-based OOP examples written in ActionScript 2.0 won't compile in ActionScript 1.0 and require Flash MX 2004 (standard or Professional edition). If you are still using ActionScript 1.0 in Flash MX 2004, consider this as an opportunity to broaden your horizons. See Chapter 10 and Chapter 12 for additional details and resources on the ActionScript differences between Flash Player 6 and Flash Player 7.

Case-Sensitivity

Many developers continue to be confused by the case-sensitivity rules in Flash MX 2004. Realize first that we are talking about two different issues: compile-time case-sensitivity and runtime case-sensitivity. The ActionScript 1.0 compiler is not case-sensitive, whereas the ActionScript 2.0 compiler is. However, runtime case-sensitivity is a function of the version of the SWF file format to which you export, not the ActionScript version used at compile time nor the version of the Flash Player plugin in which the file is played.

Runtime case-sensitivity is summarized in Table P-1, reproduced from Colin Moock's excellent book, Essential ActionScript 2.0 (O'Reilly).

Table P-1. Runtime case-sensitivity support by language, file format, and Flash Player version

Movie compiled as either ActionScript 1.0 or 2.0 and	Played in Flash Player 6	Played in Flash Player 7
Flash Player 6-format .swf file	Case-insensitive [1]	Case-insensitive 1
Flash Player 7-format .swf file	Not supported[2]	Case-sensitive

^[1] Identifiers (i.e., variable and property names), function names, frame labels, and symbols export IDs are case-insensitive in Flash Player 6-format .swf files. But reserved words such as if are case-sensitive, even in Flash Player 6.

^[2] Flash Player 6 cannot play Flash Player 7-format .swf files.