ActionScript 3.0 language fundamentals

Compile-time type checking is favored as a project’s size grows because catching type errors as early as possible becomes more important than data type flexibility. By default, the ActionScript compiler in Flash Professional and Flash Builder is set to run in strict mode to catch errors early.

To provide compile-time type checking, the compiler must know the data type information for the variables or expressions in your code. To explicitly declare a data type for a variable, use the colon operator ( : ) followed by the data type as a suffix to the variable name. To associate a data type with a parameter, use the colon operator followed by the data type. For example, the following code adds data type information to the sampleParameter parameter and declares a variable sampleData with an explicit data type:

function runtimeTest(sampleParameter:String) 
{ 
    trace(sampleParameter); 
} 
var sampleData:String = "hello"; 
runtimeTest(sampleData);

In strict mode, the ActionScript compiler reports type mismatches as compiler errors. For example, the following code declares a function parameter sampleParameter , of type Object, but later attempts to assign values of type String and Number to that parameter. In strict mode, a compiler error results.

function dynamicTest(sampleParameter:Object) 
{ 
    if (sampleParameter is String) 
    { 
        var exampleString:String = sampleParameter; // compiler error in strict mode 
        trace("String: " + exampleString); 
    } 
    else if (sampleParameter is Number) 
    { 
        var exampleNumber:Number = sampleParameter; // compiler error in strict mode 
        trace("Number: " + exampleNumber); 
    } 
}

Runtime type checking occurs in ActionScript 3.0 whether you compile in strict mode or standard mode. Consider a situation in which the value 3 is passed as an argument to a function that expects an array. In strict mode, the compiler generates an error, because the value 3 is not compatible with the data type Array . If you run in standard mode, the compiler does not complain about the type mismatch, but runtime type checking results in a runtime error.

The following example shows a function named typeTest() that expects an Array argument but is passed a value of 3. The incorrect type causes a runtime error in standard mode, because the value 3 is not a member of the parameter’s declared data type (Array).

function typeTest(sampleParameter:Array) 
{ 
    trace(sampleParameter); 
} 
var exampleNumber:Number = 3; 
typeTest(exampleNumber);  
// run-time error in ActionScript 3.0 standard mode

There are also situations where you get a runtime type error even when you are operating in strict mode. This error is possible if you use strict mode, but opt out of compile-time type checking by using an untyped variable. When you use an untyped variable, you are not eliminating type checking but rather deferring it until runtime. For example, if the exampleNumber variable in the previous example does not have a declared data type, the compiler cannot detect the type mismatch. However, a runtime error occurs because ActionScript compares the runtime value of exampleNumber , which is 3, with the type of sampleParameter , which is set to the Array data type.

function typeTest(sampleParameter:Array) 
{ 
    trace(sampleParameter); 
} 
var exampleNumber = 3; 
typeTest(exampleNumber);  
// run-time error in ActionScript 3.0

var mySprite:Sprite = new Sprite(); 
trace(mySprite is Sprite); // true 
trace(mySprite is DisplayObject);// true 
trace(mySprite is IEventDispatcher); // true

The is operator checks the inheritance hierarchy and properly reports that mySprite is compatible with the Sprite and DisplayObject classes. The is operator also checks whether mySprite inherits from any classes that implement the IEventDispatcher interface. Because the Sprite class inherits from the EventDispatcher class, which implements the IEventDispatcher interface, the is operator correctly reports that mySprite implements the same interface.

The Boolean data type includes two values: true and false . No other values are valid for variables of Boolean type. The default value of a Boolean variable that has been declared but not initialized is false .

In ActionScript 3.0, the Number data type can represent all types of numbers—integers, unsigned integers, and floating‑point numbers. It is the most flexible of numeric data types in ActionScript 3.0. However, to maximize performance, use the Number data type only for floating-point numbers or for integer values larger than the 32‑bit int and uint types can store.

Storage of floating-point numbers

The Number data type uses the 64‑bit double-precision format as specified by the IEEE Standard for Binary Floating‑Point Arithmetic (IEEE-754). This standard dictates how floating-point numbers are stored using the 64 available bits. One bit is used to designate whether the number is positive or negative. Eleven bits are used for the exponent, which is stored as base 2. The remaining 52 bits are used to store the significand (also called mantissa ), the number that is raised to the power indicated by the exponent.

By using some of its bits to store an exponent, the Number data type can store floating-point numbers significantly larger than if it used all of its bits for the significand. For example, if the Number data type used all 64 bits to store the significand, it could store a number as large as 2 ⁶⁵ - 1. By using 11 bits to store an exponent, the Number data type can raise its significand to a power of 2 ¹⁰²³ .

Although this range of numbers is enormous, it comes at the cost of precision. Because the Number data type uses 52 bits to store the significand, numbers that require more than 52 bits for accurate representation, such as the fraction 1/3, are only approximations. If your application requires absolute precision with decimal numbers, use software that implements decimal floating-point arithmetic as opposed to binary floating-point arithmetic.

To store a floating-point number, include a decimal point in the number. If you omit a decimal point, the number is stored as an integer.

NaN and other special Number values

The default value of an unassigned Number variable is NaN . The NaN value is also the result of any operation that should return a number but does not. For example, if you attempt to calculate the square root of a negative number or divide 0 by 0, the result is NaN . Other special Number values include positive infinity and negative infinity.

The int data type includes all positive and negative whole numbers from ‑2,147,483,648 (‑2 ³¹ ) through 2,147,483,647 (2 ³¹ – 1) inclusive. It is stored as a 32‑bit integer. If you do not need floating-point numbers, use the int type instead of Number because it is faster and more efficient. For values outside the range of int , use the Number data type. The int type is commonly used in counters and loops. The default value for unassigned int variables is 0.

If you try to assign a floating-point value to an int variable, ActionScript ignores the fractional (decimal) part.

The uint data type includes all positive whole numbers from 0 through 4,294,967,295 (2 ³² – 1) inclusive. It is stored as a 32‑bit integer. The default value for unassigned uint variables is 0. As with int , if you try to assign a floating‑point value to a uint variable, ActionScript ignores the fractional (decimal) part.

A uint value is always a simple binary translation of the value. Use a uint for all bit math and when working with hexadecimal values for color.

The Null data type contains only one value, null . This value is the default value for the String data type and all classes that define complex data types, including the Object class. None of the other primitive data types, Boolean , Number , int , and uint , contain the value null . At runtime, the value null is converted to the appropriate default value if you attempt to assign null to variables of type Boolean , Number , int , or uint .

Do not confuse value null with the special value undefined . When null and undefined are compared with the equality ( == ) operator, they compare as equal. However, when null and undefined are compared with the strict equality ( === ) operator, they compare as not equal.

The String data type represents a sequence of 16‑bit characters. Strings are stored internally as Unicode characters, using the UTF‑16 format. Strings are immutable values. An operation on a String value returns a new instance of the string. The default value for a variable declared with the String data type is null . The value nul is not the same as the empty string ( "" ). The value null means that the variable has no value stored in it. The empty string means that the variable has a value that is a String containing no characters.

The void data type contains only one value, undefined . You can only assign a value of undefined to variables that are untyped. Untyped variables are variables that either lack any type annotation, or use the asterisk ( * ) symbol for type annotation. You can use void only as a return type annotation.

The Object class defines the Object data type. The Object class serves as the base class for all class definitions in ActionScript. The default value for instances of the Object class is null .

The additive and multiplicative operators ( + , - , * , / ) take two operands and perform the appropriate calculation. The modulo operator returns the remainder after a division operation. Increment ( ++ ) and decrement ( -- ) are unary operators and therefore only require one operand. They either add (increment) or subtract (decrement) 1 from the expression they are used on. They can be used as either prefix or postfix operators.

var xNum:Number = 0; 
trace(++xNum); // 1 
trace(xNum); // 1

var xNum:Number = 0; 
trace(xNum++); // 0 
trace(xNum); // 1

The assignment operator assigns the value of the expression on the right to the operand on the left. The operand on the right can be any expression that ActionScript 3.0 can evaluate. The operand on the left must be a single variable, array element, or property.

Compound assignment operators perform arithmetic on a variable and then store the result in that same variable.

var x:uint = 10; 
// x is now 10 
var y:uint = (5+7)/2; 
// y is now 6 
var text:String = "Hello"; 
// text is now Hello

var x:uint = 5; 
x += 5; // x is now 10

var x:uint = 5; 
x -= 5; // x is now 0

var x:uint = 5; 
x *= 5; // x is now 25

var x:uint = 5; 
x /= 5; // x is now 1

var x:uint = 13; 
x %= 5; // x is now 3

The equality operators take two operands, compare their values, and return a Boolean value. The relational operators take two operands, compare their values, and return a Boolean value.

var a:uint = 13; 
var b:uint = 13; 
trace(a==b); // true 
 
var c:String = "Hello"; 
var d:String = "World"; 
trace(c==d); // false

var a:uint = 13; 
var b:uint = 13; 
trace(a!=b); // false 
 
var c:String = "Hello"; 
var d:String = "World"; 
trace(c==d); // true

var a:uint = 13; 
var b:Number = 13; 
trace(a===b); // false 
 
var c:uint = 22; 
var d:uint = 22; 
trace(c===d); // true

var a:uint = 13; 
var b:Number = 13; 
trace(a!==b); // true 
 
var c:uint = 22; 
var d:uint = 22; 
trace(c!==d); // false

var x:int = 27; 
var y:int = 42; 
var z:int = 101; 
trace(x<y); // true 
trace(z<y); // false

var x:int = 27; 
var y:int = 42; 
var z:int = 101; 
trace(x>y); // false 
trace(z>y); // true

var x:int = 27; 
var y:int = 42; 
var z:int = 42; 
trace(x<=y); // true 
trace(y<=z); // true

var x:int = 27; 
var y:int = 42; 
var z:int = 42; 
trace(x>=y); // false 
trace(y>=z); // true

The logical operators take two operands and return a Boolean result. They are frequently used to combine conditions.

The bitwise logical operators take two operands and perform bit-level logical operations.

The bitwise shift operators take two operands and shift the bits of the first operand to the extent specified by the second operand.

The primary operators include those operators used for creating Array and Object literals, grouping expressions, calling functions, instantiating class instances, and accessing properties.

The conditional operator is a ternary operator, which means that it takes three operands. The conditional operator is a shorthand method of applying the if..else conditional statement.

.

/

:

void

Natural numbers are the numbers you are most familiar with. You use them to count the things around you. A natural number is zero and any number obtained by repeatedly adding 1—in other words, 0 and any positive, whole number. Examples of natural numbers are 100, 0, 45,645, 32.

Integers include all natural numbers plus all negative whole numbers. Examples of integers are ‑24, ‑1, 100, 0, 45,645.

Any rational or irrational number is a real number. A rational number is any number that can be expressed as the quotient or fraction of two integers or with a decimal. Examples of rational numbers are ‑249, ‑1, 0, 3/7, ‑2/5, and .342. Irrational numbers are numbers that can’t accurately be expressed as a fraction or with a decimal. The best-known irrational numbers are π, e, and the √2. Floating-point numbers represent real numbers in computers.

In ActionScript 3.0, the Number data type can represent all types of numbers—integers, unsigned integers, and floating‑point numbers. It is the most flexible of numeric data types in ActionScript 3.0. However, to maximize performance, use the Number data type only for floating-point numbers or for integer values larger than the 32-bit int and uint types can store.

Storage of floating-point numbers

The Number data type uses the 64‑bit double-precision format as specified by the IEEE Standard for Binary Floating‑Point Arithmetic (IEEE-754). This standard dictates how floating-point numbers are stored using the 64 available bits. One bit is used to designate whether the number is positive or negative. Eleven bits are used for the exponent, which is stored as base 2. The remaining 52 bits are used to store the significand (also called mantissa ), the number that is raised to the power indicated by the exponent.

By using some of its bits to store an exponent, the Number data type can store floating-point numbers significantly larger than if it used all of its bits for the significand. For example, if the Number data type used all 64 bits to store the significand, it could store a number as large as 2 ⁶⁵ - 1. By using 11 bits to store an exponent, the Number data type can raise its significand to a power of 2 ¹⁰²³ .

Although this range of numbers is enormous, it comes at the cost of precision. Because the Number data type uses 52 bits to store the significand, numbers that require more than 52 bits for accurate representation, such as the fraction 1/3, are only approximations. If your application requires absolute precision with decimal numbers, use software that implements decimal floating-point arithmetic as opposed to binary floating-point arithmetic.

To store a floating-point number, include a decimal point in the number. If you omit a decimal point, the number is stored as an integer.

NaN and other special Number values

The default value of an unassigned Number variable is NaN . The NaN value is also the result of any operation that should return a number but does not. For example, if you attempt to calculate the square root of a negative number or divide 0 by 0, the result is NaN . Other special Number values include positive infinity and negative infinity.

The int data type includes all positive and negative whole numbers from ‑2,147,483,648 (‑2 ³¹ ) through 2,147,483,647 (2 ³¹ – 1) inclusive. It is stored as a 32‑bit integer. If you do not need floating-point numbers, use the int type instead of Number because it is faster and more efficient. For values outside the range of int , use the Number data type. The int type is commonly used in counters and loops. The default value for unassigned int variables is 0.

If you try to assign a floating-point value to an int variable, ActionScript ignores the fractional (decimal) part.

The uint data type includes all positive whole numbers from 0 through 4,294,967,295 (2 ³² – 1) inclusive. It is stored as a 32‑bit integer. The default value for unassigned uint variables is 0. As with int , if you try to assign a floating‑point value to a uint variable, ActionScript ignores the fractional (decimal) part.

A uint value is always a simple binary translation of the value. Use a uint for all bit math and when working with hexadecimal values for color.

When you develop applications using Adobe Flash CS4 Professional, you have access to the timeline, which provides a steady, frame-by-frame progression through your application. In pure ActionScript projects, however, you must rely on other timing mechanisms.

A simple analog clock example illustrates these two date and time concepts:

• Getting the current date and time and extracting values for the hours, minutes, and seconds

• Using a Timer to set the pace of an application

  To get the application files for this sample, see www.adobe.com/go/learn_programmingAS3samples_flash . The SimpleClock application files can be found in the folder Samples/SimpleClock. The application consists of the following files:

  File	Description
  SimpleClockApp.mxml or SimpleClockApp.fla	The main application file in Flash (FLA) or Flex (MXML).
  com/example/programmingas3/simpleclock/SimpleClock.as	The main application file.
  com/example/programmingas3/simpleclock/AnalogClockFace.as	Draws a round clock face and hour, minute, and seconds hands based on the time.

All of the calendar date and time management functions in ActionScript 3.0 are concentrated in the top-level Date class. The Date class contains methods and properties that let you handle dates and times in either Coordinated Universal Time (UTC) or in local time specific to a time zone. UTC is a standard time definition that is essentially the same as Greenwich Mean Time (GMT).

In programming parlance, a string is a text value—a sequence of letters, numbers, or other characters strung together into a single value. For instance, this line of code creates a variable with the data type String and assigns a literal string value to that variable:

var albumName:String = "Three for the money";

As this example shows, in ActionScript you can denote a string value by surrounding text with double or single quotation marks. Here are several more examples of strings:

"Hello" 
"555-7649" 
"http://www.adobe.com/"

Any time you manipulate a piece of text in ActionScript, you are working with a string value. The ActionScript String class is the data type you can use to work with text values. String instances are frequently used for properties, method parameters, and so forth in many other ActionScript classes.

The String class is used to represent string (textual) data in ActionScript 3.0. ActionScript strings support both ASCII and Unicode characters. The simplest way to create a string is to use a string literal. To declare a string literal, use straight double quotation mark ( " ) or single quotation mark ( ' ) characters. For example, the following two strings are equivalent:

var str1:String = "hello"; 
var str2:String = 'hello';

You can also declare a string by using the new operator, as follows:

var str1:String = new String("hello");   
var str2:String = new String(str1); 
var str3:String = new String();       // str3 == ""

The following two strings are equivalent:

var str1:String = "hello";  
var str2:String = new String("hello");

To use single quotation marks ( ' ) within a string literal defined with single quotation mark ( ' ) delimiters, use the backslash escape character ( \ ). Similarly, to use double quotation marks ( " ) within a string literal defined with double quotation marks ( " ) delimiters, use the backslash escape character ( \ ). The following two strings are equivalent:

var str1:String = "That's \"A-OK\""; 
var str2:String = 'That\'s "A-OK"';

You may choose to use single quotation marks or double quotation marks based on any single or double quotation marks that exist in a string literal, as in the following:

var str1:String = "ActionScript <span class='heavy'>3.0</span>"; 
var str2:String = '<item id="155">banana</item>';

Keep in mind that ActionScript distinguishes between a straight single quotation mark ( ' ) and a left or right single quotation mark ( ' or ' ). The same is true for double quotation marks. Use straight quotation marks to delineate string literals. When pasting text from another source into ActionScript, be sure to use the correct characters.

As the following table shows, you can use the backslash escape character ( \ ) to define other characters in string literals:

Every string has a length property, which is equal to the number of characters in the string:

var str:String = "Adobe"; 
trace(str.length);            // output: 5

An empty string and a null string both have a length of 0, as the following example shows:

var str1:String = new String(); 
trace(str1.length);           // output: 0 
 
str2:String = ''; 
trace(str2.length);           // output: 0

Every character in a string has an index position in the string (an integer). The index position of the first character is 0. For example, in the following string, the character y is in position 0 and the character w is in position 5:

"yellow"

You can examine individual characters in various positions in a string using the charAt() method and the charCodeAt() method, as in this example:

var str:String = "hello world!"; 
for (var i:int = 0; i < str.length; i++) 
{ 
    trace(str.charAt(i), "-", str.charCodeAt(i)); 
}

When you run this code, the following output is produced:

h - 104 
e - 101 
l - 108 
l - 108 
o - 111 
- 32 
w - 119 
o - 111 
r - 114 
l - 108 
d - 100 
! - 33 

You can also use character codes to define a string using the fromCharCode() method, as the following example shows:

var myStr:String = String.fromCharCode(104,101,108,108,111,32,119,111,114,108,100,33); 
        // Sets myStr to "hello world!"

You can use the following operators to compare strings: < , <= , != , == , => , and > . These operators can be used with conditional statements, such as if and while , as the following example shows:

var str1:String = "Apple"; 
var str2:String = "apple"; 
if (str1 < str2) 
{ 
    trace("A < a, B < b, C < c, ..."); 
}

When using these operators with strings, ActionScript considers the character code value of each character in the string, comparing characters from left to right, as in the following:

trace("A" < "B"); // true 
trace("A" < "a"); // true  
trace("Ab" < "az"); // true  
trace("abc" < "abza"); // true

Use the == and != operators to compare strings with each other and to compare strings with other types of objects, as the following example shows:

var str1:String = "1"; 
var str1b:String = "1"; 
var str2:String = "2"; 
trace(str1 == str1b); // true 
trace(str1 == str2); // false 
var total:uint = 1; 
trace(str1 == total); // true

You can obtain a String representation for any kind of object. All objects have a toString() method for this purpose:

var n:Number = 99.47; 
var str:String = n.toString(); 
    // str == "99.47"

When using the + concatenation operator with a combination of String objects and objects that are not strings, you do not need to use the toString() method. For details on concatenation, see the next section.

The String() global function returns the same value for a given object as the value returned by the object calling the toString() method.

Concatenation of strings means taking two strings and joining them sequentially into one. For example, you can use the + operator to concatenate two strings:

var str1:String = "green"; 
var str2:String = "ish"; 
var str3:String = str1 + str2; // str3 == "greenish"

You can also use the += operator to the produce the same result, as the following example shows:

var str:String = "green"; 
str += "ish"; // str == "greenish"

Additionally, the String class includes a concat() method, which can be used as follows:

var str1:String = "Bonjour"; 
var str2:String = "from"; 
var str3:String = "Paris"; 
var str4:String = str1.concat(" ", str2, " ", str3); 
// str4 == "Bonjour from Paris"

If you use the + operator (or the += operator) with a String object and an object that is not a string, ActionScript automatically converts the nonstring object to a String object in order to evaluate the expression, as shown in this example:

var str:String = "Area = "; 
var area:Number = Math.PI * Math.pow(3, 2); 
str = str + area; // str == "Area = 28.274333882308138"

However, you can use parentheses for grouping to provide context for the + operator, as the following example shows:

trace("Total: $" + 4.55 + 1.45); // output: Total: $4.551.45 
trace("Total: $" + (4.55 + 1.45)); // output: Total: $6

Substrings are sequential characters within a string. For example, the string "abc" has the following substrings: "" , "a" , "ab" , "abc" , "b" , "bc" , "c" . You can use ActionScript methods to locate substrings of a string.

Patterns are defined in ActionScript by strings or by regular expressions. For example, the following regular expression defines a specific pattern—the letters A, B, and C followed by a digit character (the forward slashes are regular expression delimiters):

/ABC\d/

ActionScript includes methods for finding patterns in strings and for replacing found matches with replacement substrings. These methods are described in the following sections.

Regular expressions can define intricate patterns. For more information, see Using regular expressions.

As the following example shows, the toLowerCase() method and the toUpperCase() method convert alphabetical characters in the string to lowercase and uppercase, respectively:

var str:String = "Dr. Bob Roberts, #9." 
trace(str.toLowerCase()); // dr. bob roberts, #9. 
trace(str.toUpperCase()); // DR. BOB ROBERTS, #9.

After these methods are executed, the source string remains unchanged. To transform the source string, use the following code:

str = str.toUpperCase();

These methods work with extended characters, not simply a–z and A–Z:

var str:String = "José Barça"; 
trace(str.toUpperCase(), str.toLowerCase()); // JOSÉ BARÇA josé barça

Sometimes functions need data to successfully complete their defined tasks. When defining a function, the needed data is referred to as a parameter . When the data is being used within the function body, it is also referred to as a parameter. The actual data sent to a function at the time of a function call, is referred to as an argument . Two different names are used to distinguish where the data is.

To create parameters for a function, declare a list of parameters and their data types in the parenthesis in a function definition. Separate the parameters with commas. Not all functions require data—only declare parameters when a function needs data to complete its task.

If a function has parameters defined, providing arguments at the time the function is called is required.

private function optionalParameterExample(x:int, y:int = 3, z:int = 5):void { 
    trace(x, y, z); 
} 
optionalParameterExample(1); // 1 3 5

public function passPrimitives(firstPrimParam:int, secondPrimParam:String):void{ 
    firstPrimParam++; 
    secondPrimParam+="test"; 
    trace(firstPrimParam, secondPrimParam); 
} 
 
var firstPrimValue:int = 10; 
var secondPrimValue:String = "Hello world"; 
trace(firstPrimValue, secondPrimValue);// 10 Hello world 
passPrimitives(firstPrimValue, secondPrimValue); // 11 Hello world test 
trace(firstPrimValue, secondPrimValue);// 10 Hello world

public function passByRef(objParam:Object):void { 
    objParam.x++; 
    objParam.y++; 
    trace(objParam.x, objParam.y); 
} 
var objVar:Object = {x:10, y:15}; 
trace(objVar.x, objVar.y); // 10 15 
passByRef(objVar); // 11 16 
trace(objVar.x, objVar.y); // 11 16

public function traceArgs(... args):void { 
    for (var i:int = 0; i < args.length; i++){ 
        trace(args[i]); 
    } 
} 
 
traceArgs(10, 25, 40); 
 
// output: 
// 10 
// 25 
// 40

public function traceArgs(firstParam:int, ... args){ 
    for (var i:int = 0; i < args.length; i++){ 
        trace(args[i]); 
    } 
} 
 
traceArgs(10, 25, 40); 
 
// output: 
// 25 
// 40

Some functions simply perform a task. If you are asked to raise your hand, you raise your hand. You do not say anything or do anything but raise your hand. Functions can be similar, only doing a task.

Other functions do a task and return data. If you are asked to tell someone your name, you say (task) your name (returned data). Functions that return data work in the same way as you did when asked your name. Typically the data a function returns is the result of a calculation or conditional test.

private function myTraceFunction():void{ 
    trace("Hello world"); 
} 
 
myTraceFunction(); // Hello world

public function doubledValue(baseNum:int):int { 
    return (baseNum * 2); 
}

public function doubledValue(baseNum:int):int { 
    return (baseNum * 2); 
    trace("after return"); // This trace statement will not be executed. 
}

All display objects are subclasses of the DisplayObject class, and as such they inherit the properties and methods of the DisplayObject class. The properties inherited are basic properties that apply to all display objects. For example, each display object has an x property and a y property that specifies the object’s position in its display object container.

You cannot create a DisplayObject instance using the DisplayObject class constructor. You must create another type of object (an object that is a subclass of the DisplayObject class), such as a Sprite, to instantiate an object with the new operator. Also, if you want to create a custom display object class, you must create a subclass of one of the display object subclasses that has a usable constructor function (such as the Shape class or the Sprite class). For more information, see the DisplayObject class description in the ActionScript 3.0 Reference for the Adobe Flash Platform .

When you instantiate a display object, it will not appear on-screen (on the Stage) until you add the display object instance to a display object container that is on the display list. For example, in the following code, the myText TextField object would not be visible if you omitted the last line of code. In the last line of code, the this keyword must refer to a display object container that is already added to the display list.

import flash.display.*; 
import flash.text.TextField; 
var myText:TextField = new TextField(); 
myText.text = "Buenos dias."; 
this.addChild(myText);

When you add any visual element to the Stage, that element becomes a child of the Stage object. The first SWF file loaded in an application (for example, the one that you embed in an HTML page) is automatically added as a child of the Stage. It can be an object of any type that extends the Sprite class.

Any display objects that you create without using ActionScript—for example, by adding an MXML tag in a Flex MXML file or by placing an item on the Stage in Flash Professional—are added to the display list. Although you do not add these display objects through ActionScript, you can access them through ActionScript. For example, the following code adjusts the width of an object named button1 that was added in the authoring tool (not through ActionScript):

button1.width = 200;

If a DisplayObjectContainer object is deleted from the display list, or if it is moved or transformed in some other way, each display object in the DisplayObjectContainer is also deleted, moved, or transformed.

A display object container is itself a type of display object—it can be added to another display object container. For example, the following image shows a display object container, pictureScreen , that contains one outline shape and four other display object containers (of type PictureFrame):

View full size graphic

A.

A shape defining the border of the pictureScreen display object container

B.

Four display object containers that are children of the pictureScreen object

In order to have a display object appear in the display list, you must add it to a display object container that is on the display list. You do this by using the addChild() method or the addChildAt() method of the container object. For example, without the final line of the following code, the myTextField object would not be displayed:

var myTextField:TextField = new TextField(); 
myTextField.text = "hello"; 
this.root.addChild(myTextField);

In this code sample, this.root points to the MovieClip display object container that contains the code. In your actual code, you may specify a different container.

Use the addChildAt() method to add the child to a specific position in the child list of the display object container. These zero-based index positions in the child list relate to the layering (the front-to-back order) of the display objects. For example, consider the following three display objects. Each object was created from a custom class called Ball.

The layering of these display objects in their container can be adjusted using the addChildAt() method. For example, consider the following code:

ball_A = new Ball(0xFFCC00, "a"); 
ball_A.name = "ball_A"; 
ball_A.x = 20; 
ball_A.y = 20; 
container.addChild(ball_A); 
 
ball_B = new Ball(0xFFCC00, "b"); 
ball_B.name = "ball_B"; 
ball_B.x = 70; 
ball_B.y = 20; 
container.addChild(ball_B); 
 
ball_C = new Ball(0xFFCC00, "c"); 
ball_C.name = "ball_C"; 
ball_C.x = 40; 
ball_C.y = 60; 
container.addChildAt(ball_C, 1);

After executing this code, the display objects are positioned as follows in the container DisplayObjectContainer object. Notice the layering of the objects.

To reposition an object to the top of the display list, simply re-add it to the list. For example, after the previous code, to move ball_A to the top of the stack, use this line of code:

container.addChild(ball_A);

This code effectively removes ball_A from its location in container ’s display list, and re-adds it to the top of the list—which has the end result of moving it to the top of the stack.

You can use the getChildAt() method to verify the layer order of the display objects. The getChildAt() method returns child objects of a container based on the index number you pass it. For example, the following code reveals names of display objects at different positions in the child list of the container DisplayObjectContainer object:

trace(container.getChildAt(0).name); // ball_A 
trace(container.getChildAt(1).name); // ball_C 
trace(container.getChildAt(2).name); // ball_B

If you remove a display object from the parent container’s child list, the higher elements on the list each move down a position in the child index. For example, continuing with the previous code, the following code shows how the display object that was at position 2 in the container DisplayObjectContainer moves to position 1 if a display object that is lower in the child list is removed:

container.removeChild(ball_C); 
trace(container.getChildAt(0).name); // ball_A 
trace(container.getChildAt(1).name); // ball_B

The removeChild() and removeChildAt() methods do not delete a display object instance entirely. They simply remove it from the child list of the container. The instance can still be referenced by another variable. (Use the delete operator to completely remove an object.)

Because a display object has only one parent container, you can add an instance of a display object to only one display object container. For example, the following code shows that the display object tf1 can exist in only one container (in this case, a Sprite, which extends the DisplayObjectContainer class):

tf1:TextField = new TextField(); 
tf2:TextField = new TextField(); 
tf1.name = "text 1"; 
tf2.name = "text 2"; 
 
container1:Sprite = new Sprite(); 
container2:Sprite = new Sprite(); 
 
container1.addChild(tf1); 
container1.addChild(tf2); 
container2.addChild(tf1); 
 
trace(container1.numChildren); // 1 
trace(container1.getChildAt(0).name); // text 2 
trace(container2.numChildren); // 1 
trace(container2.getChildAt(0).name); // text 1

If you add a display object that is contained in one display object container to another display object container, it is removed from the first display object container’s child list.

In addition to the methods described above, the DisplayObjectContainer class defines several methods for working with child display objects, including the following:

• contains() : Determines whether a display object is a child of a DisplayObjectContainer.

• getChildByName() : Retrieves a display object by name.

• getChildIndex() : Returns the index position of a display object.

• setChildIndex() : Changes the position of a child display object.

• swapChildren() : Swaps the front-to-back order of two display objects.

• swapChildrenAt() : Swaps the front-to-back order of two display objects, specified by their index values.

For more information, see the relevant entries in the ActionScript 3.0 Reference for the Adobe Flash Platform .

Recall that a display object that is off the display list—one that is not included in a display object container that is a child of the Stage—is known as an off-list display object.

As you’ve seen, the display list is a tree structure. At the top of the tree is the Stage, which can contain multiple display objects. Those display objects that are themselves display object containers can contain other display objects, or display object containers.

The DisplayObjectContainer class includes properties and methods for traversing the display list, by means of the child lists of display object containers. For example, consider the following code, which adds two display objects, title and pict , to the container object (which is a Sprite, and the Sprite class extends the DisplayObjectContainer class):

var container:Sprite = new Sprite(); 
var title:TextField = new TextField(); 
title.text = "Hello"; 
var pict:Loader = new Loader(); 
var url:URLRequest = new URLRequest("banana.jpg"); 
pict.load(url); 
pict.name = "banana loader"; 
container.addChild(title); 
container.addChild(pict);

The getChildAt() method returns the child of the display list at a specific index position:

trace(container.getChildAt(0) is TextField); // true

You can also access child objects by name. Each display object has a name property, and if you don’t assign it, Flash Player or AIR assigns a default value, such as "instance1" . For example, the following code shows how to use the getChildByName() method to access a child display object with the name "banana loader" :

trace(container.getChildByName("banana loader") is Loader); // true

Using the getChildByName() method can result in slower performance than using the getChildAt() method.

Since a display object container can contain other display object containers as child objects in its display list, you can traverse the full display list of the application as a tree. For example, in the code excerpt shown earlier, once the load operation for the pict Loader object is complete, the pict object will have one child display object, which is the bitmap, loaded. To access this bitmap display object, you can write pict.getChildAt(0) . You can also write container.getChildAt(0).getChildAt(0) (since container.getChildAt(0) == pict ).

The following function provides an indented trace() output of the display list from a display object container:

function traceDisplayList(container:DisplayObjectContainer,                                                indentString:String = ""):void 
{ 
    var child:DisplayObject; 
    for (var i:uint=0; i < container.numChildren; i++) 
    { 
        child = container.getChildAt(i); 
        trace(indentString, child, child.name);  
        if (container.getChildAt(i) is DisplayObjectContainer) 
        { 
            traceDisplayList(DisplayObjectContainer(child), indentString + "    ") 
        } 
    } 
}

The Stage class overrides most properties and methods of the DisplayObject class. If you call one of these overridden properties or methods, Flash Player and AIR throw an exception. For example, the Stage object does not have x or y properties, since its position is fixed as the main container for the application. The x and y properties refer to the position of a display object relative to its container, and since the Stage is not contained in another display object container, these properties do not apply.

With several options to choose from, one of the important decisions you’ll make when you’re working with display objects is which display object to use for what purpose. Here are some guidelines to help you decide. These same suggestions apply whether you need an instance of a class or you’re choosing a base class for a class you’re creating:

• If you don’t need an object that can be a container for other display objects (that is, you just need one that serves as a stand-alone screen element), choose one of these DisplayObject or InteractiveObject subclasses, depending on what it will be used for:

  • Bitmap for displaying a bitmap image.

  • TextField for adding text.

  • Video for displaying video.

  • Shape for a “canvas” for drawing content on-screen. In particular, if you want to create an instance for drawing shapes on the screen, and it won’t be a container for other display objects, you’ll gain significant performance benefits using Shape instead of Sprite or MovieClip.

  • MorphShape, StaticText, or SimpleButton for items created by the Flash authoring tool. (You can’t create instances of these classes programmatically, but you can create variables with these data types to refer to items created using the Flash authoring tool.)

• If you need a variable to refer to the main Stage, use the Stage class as its data type.

• If you need a container for loading an external SWF file or image file, use a Loader instance. The loaded content will be added to the display list as a child of the Loader instance. Its data type will depend on the nature of the loaded content, as follows:

  • A loaded image will be a Bitmap instance.

  • A loaded SWF file written in ActionScript 3.0 will be a Sprite or MovieClip instance (or an instance of a subclass of those classes, as specified by the content creator).

  • A loaded SWF file written in ActionScript 1.0 or ActionScript 2.0 will be an AVM1Movie instance.

• If you need an object to serve as a container for other display objects (whether or not you’ll also be drawing onto the display object using ActionScript), choose one of the DisplayObjectContainer subclasses:

  • Sprite if the object will be created using only ActionScript, or as the base class for a custom display object that will be created and manipulated solely with ActionScript.

  • MovieClip if you’re creating a variable to refer to a movie clip symbol created in the Flash authoring tool.

• If you are creating a class that will be associated with a movie clip symbol in the Flash library, choose one of these DisplayObjectContainer subclasses as your class’s base class:

  • MovieClip if the associated movie clip symbol has content on more than one frame

  • Sprite if the associated movie clip symbol has content only on the first frame

Organize your classes into related groups. If you were building an application that draws, performs special calculations, and uses custom user interface components, place all of your drawing classes in a draw package, your calculations classes into a calculations package, and your user interface component classes in a ui package.

You can also include embedded dots (dot syntax) in your package name to create nested packages. Dot syntax allows you to create a hierarchical organization of packages. A good example of this practice is the flash.display package provided by ActionScript 3.0. The display package is nested inside the flash package.

The organization and hierarchy you create in code is also visible on your file system. Your class files exist in folders with the same names and nested structure as your packages.

package samples { 
    public class SampleCode { 
        public var sampleGreeting:String; 
         
        public function SampleCode() { 
        } 
        public function sampleFunction() { 
            trace(sampleGreeting + " from sampleFunction()"); 
        } 
    } 
}

The compiler also qualifies the names of any properties or methods, so that sampleGreeting and sampleFunction() become samples.SampleCode.sampleGreeting and samples.SampleCode.sampleFunction() , respectively.

package langref { 
    public class SampleCode {} 
}

package { 
    import samples.SampleCode; 
    import langref.SampleCode; 
    public class TestApplication { 
        var firstExampleVar:samples.SampleCode = new samples.SampleCode(); 
        var secondExampleVar:langref.SampleCode = new langref.SampleCode(); 
        public function TestApplication(){ } 
    } 
}

package com.example.samples { 
    public class SampleCode { 
        public var sampleGreeting:String; 
         
        public function SampleCode() { 
        } 
        public function sampleFunction() { 
            trace(sampleGreeting + " from sampleFunction()"); 
        } 
    } 
}

You control where your code is available by using access control attributes when declaring variables and defining functions. You control where classes are available by using access control attributes with packages.

// SampleCode.as file 
package samples 
{ 
    public class SampleCode {} 
} 
 
// CodeFormatter.as file 
package samples 
{ 
    class CodeFormatter {} 
}

package examples{ 
    import samples.SampleCode; 
    import samples.CodeFormatter; 
    public class UsingPackages { 
        var mySample:SampleCode = new SampleCode(); // okay, public class 
        var myFormatter:CodeFormatter = new CodeFormatter(); // error 
         
        public function UsingPackages(){ 
        } 
    } 
}

The for loop allows you to iterate through a variable for a specific range of values. You must supply three expressions in a for statement: a variable that is set to an initial value, a conditional statement that determines when the looping ends, and an expression that changes the value of the variable with each loop. For example, the following code loops five times. The value of the variable i starts at 0 and ends at 4, and the output is the numbers 0 through 4, each on its own line.

var i:int; 
for (i = 0; i < 5; i++) 
{ 
    trace(i); 
}

The for..in loop iterates through the properties of an object, or the elements of an array. For example, you can use a for..in loop to iterate through the properties of a generic object (object properties are not kept in any particular order, so properties may appear in a seemingly random order):

var myObj:Object = {x:20, y:30}; 
for (var i:String in myObj) 
{ 
    trace(i + ": " + myObj[i]); 
} 
// output: 
// x: 20 
// y: 30

You can also iterate through the elements of an array:

var myArray:Array = ["one", "two", "three"]; 
for (var i:String in myArray) 
{ 
    trace(myArray[i]); 
} 
// output: 
// one 
// two 
// three

What you cannot do is iterate through the properties of an object if it is an instance of a sealed class (including built-in classes and user-defined classes). You can only iterate through the properties of a dynamic class. Even with instances of dynamic classes, you can only iterate through properties that are added dynamically.

The for each..in loop iterates through the items of a collection, which can be tags in an XML or XMLList object, the values held by object properties, or the elements of an array. For example, as the following excerpt shows, you can use a for each..in loop to iterate through the properties of a generic object, but unlike the for..in loop, the iterator variable in a for each..in loop contains the value held by the property instead of the name of the property:

var myObj:Object = {x:20, y:30}; 
for each (var num in myObj) 
{ 
    trace(num); 
} 
// output: 
// 20 
// 30

You can iterate through an XML or XMLList object, as the following example shows:

var myXML:XML = <users> 
    <fname>Jane</fname> 
    <fname>Susan</fname> 
    <fname>John</fname> 
</users>; 
 
for each (var item in myXML.fname) 
{ 
    trace(item); 
} 
/* output 
Jane 
Susan 
John 
*/

You can also iterate through the elements of an array, as this example shows:

var myArray:Array = ["one", "two", "three"]; 
for each (var item in myArray) 
{ 
    trace(item); 
} 
// output: 
// one 
// two 
// three

You cannot iterate through the properties of an object if the object is an instance of a sealed class. Even for instances of dynamic classes, you cannot iterate through any fixed properties, which are properties defined as part of the class definition.

The while loop is like an if statement that repeats as long as the condition is true . For example, the following code produces the same output as the for loop example:

var i:int = 0; 
while (i < 5) 
{ 
    trace(i); 
    i++; 
}

One disadvantage of using a while loop instead of a for loop is that infinite loops are easier to write with while loops. The for loop example code does not compile if you omit the expression that increments the counter variable, but the while loop example does compile if you omit that step. Without the expression that increments i , the loop becomes an infinite loop.

The do..while loop is a while loop that guarantees that the code block is executed at least once, because the condition is checked after the code block is executed. The following code shows a simple example of a do..while loop that generates output even though the condition is not met:

var i:int = 5; 
do 
{ 
    trace(i); 
    i++; 
} while (i < 5); 
// output: 5

The if..else conditional statement allows you to test a condition and execute a block of code if that condition exists, or execute an alternative block of code if the condition does not exist. For example, the following code tests whether the value of x exceeds 20, generates a trace() function if it does, or generates a different trace() function if it does not:

if (x > 20) 
{ 
    trace("x is > 20"); 
} 
else 
{ 
    trace("x is <= 20"); 
}

If you do not want to execute an alternative block of code, you can use the if statement without the else statement.

You can test for more than one condition using the if..else if conditional statement. For example, the following code not only tests whether the value of x exceeds 20, but also tests whether the value of x is negative:

if (x > 20) 
{ 
    trace("x is > 20"); 
} 
else if (x < 0) 
{ 
    trace("x is negative"); 
}

If an if or else statement is followed by only one statement, the statement does not need to be enclosed in curly brackets. For example, the following code does not use curly brackets:

if (x > 0) 
    trace("x is positive"); 
else if (x < 0)  
    trace("x is negative"); 
else 
    trace("x is 0");

However, Adobe recommends that you always use curly brackets, because unexpected behavior can occur if statements are later added to a conditional statement that lacks curly brackets. For example, in the following code the value of positiveNums increases by 1 whether or not the condition evaluates to true :

var x:int; 
var positiveNums:int = 0; 
 
if (x > 0) 
    trace("x is positive"); 
    positiveNums++; 
 
trace(positiveNums); // 1

The switch statement is useful if you have several execution paths that depend on the same condition expression. It provides functionality similar to a long series of if..else if statements, but is somewhat easier to read. Instead of testing a condition for a Boolean value, the switch statement evaluates an expression and uses the result to determine which block of code to execute. Blocks of code begin with a case statement and end with a break statement. For example, the following switch statement prints the day of the week, based on the day number returned by the Date.getDay() method:

var someDate:Date = new Date(); 
var dayNum:uint = someDate.getDay(); 
switch(dayNum) 
{ 
    case 0: 
        trace("Sunday"); 
        break; 
    case 1: 
        trace("Monday"); 
        break; 
    case 2: 
        trace("Tuesday"); 
        break; 
    case 3: 
        trace("Wednesday"); 
        break; 
    case 4: 
        trace("Thursday"); 
        break; 
    case 5: 
        trace("Friday"); 
        break; 
    case 6: 
        trace("Saturday"); 
        break; 
    default: 
        trace("Out of range"); 
        break; 
}

Often in programming you’ll need to work with a set of items rather than a single object. For example, in a music player application, you might want to have a list of songs waiting to be played. You wouldn’t want to have to create a separate variable for each song on that list. It would be preferable to have all the Song objects together in a bundle, and be able to work with them as a group.

An array is a programming element that acts as a container for a set of items, such as a list of songs. Most commonly all the items in an array are instances of the same class, but that is not a requirement in ActionScript. The individual items in an array are known as the array’s elements . You can think of an array as a file drawer for variables. Variables can be added as elements in the array, which is like placing a folder into the file drawer. You can work with the array as a single variable (like carrying the whole drawer to a different location). You can work with the variables as a group (like flipping through the folders one by one searching for a piece of information). You can also access them individually (like opening the drawer and selecting a single folder).

For example, imagine you’re creating a music player application where a user can select multiple songs and add them to a playlist. In your ActionScript code, you have a method named addSongsToPlaylist() , which accepts a single array as a parameter. No matter how many songs you want to add to the list (a few, a lot, or even only one), you call the addSongsToPlaylist() method only one time, passing it the array containing the Song objects. Inside the addSongsToPlaylist() method, you can use a loop to go through the array’s elements (the songs) one by one and actually add them to the playlist.

The most common type of ActionScript array is an indexed array . In an indexed array each item is stored in a numbered slot (known as an index ). Items are accessed using the number, like an address. Indexed arrays work well for most programming needs. The Array class is one common class that’s used to represent an indexed array.

Often, an indexed array is used to store multiple items of the same type (objects that are instances of the same class). The Array class doesn’t have any means for restricting the type of items it contains. The Vector class is a type of indexed array in which all the items in a single array are the same type. Using a Vector instance instead of an Array instance can also provide performance improvements and other benefits. The Vector class is available starting with Flash Player 10 and Adobe AIR 1.5.

A special use of an indexed array is a multidimensional array . A multidimensional array is an indexed array whose elements are indexed arrays (which in turn contain other elements).

Another type of array is an associative array , which uses a string key instead of a numeric index to identify individual elements. Finally, ActionScript 3.0 also includes the Dictionary class, which represents a dictionary . A dictionary is an array that allows you to use any type of object as a key to distinguish between elements.

Indexed arrays store a series of one or more values organized such that each value can be accessed using an unsigned integer value. The first index is always the number 0, and the index increments by 1 for each subsequent element added to the array. In ActionScript 3.0, two classes are used as indexed arrays: the Array class and the Vector class.

Indexed arrays use an unsigned 32-bit integer for the index number. The maximum size of an indexed array is 2 ³² - 1 or 4,294,967,295. An attempt to create an array that is larger than the maximum size results in a run-time error.

To access an individual element of an indexed array, you use the array access ( [] ) operator to specify the index position of the element you wish to access. For example, the following code represents the first element (the element at index 0) in an indexed array named songTitles :

songTitles[0]

The combination of the array variable name followed by the index in square brackets functions as a single identifier. (In other words, it can be used in any way a variable name can). You can assign a value to an indexed array element by using the name and index on the left side of an assignment statement:

songTitles[1] = "Symphony No. 5 in D minor";

Likewise, you can retrieve the value of an indexed array element by using the name and index on the right side of an assignment statement:

var nextSong:String = songTitles[2];

You can also use a variable in the square brackets rather than providing an explicit value. (The variable must contain a non-negative integer value such as a uint, a positive int, or a positive integer Number instance). This technique is commonly used to “loop over” the elements in an indexed array and perform an operation on some or all the elements. The following code listing demonstrates this technique. The code uses a loop to access each value in an Array object named oddNumbers . It uses the trace() statement to print each value in the form “oddNumber[ index ] = value ”:

var oddNumbers:Array = [1, 3, 5, 7, 9, 11]; 
var len:uint = oddNumbers.length; 
for (var i:uint = 0; i < len; i++) 
{ 
    trace("oddNumbers[" + i.toString() + "] = " + oddNumbers[i].toString()); 
}

A property represents one of the pieces of data that are bundled together in an object. An example song object can have properties named artist and title ; the MovieClip class has properties like rotation , x , width , and alpha . You work with properties like individual variables. In fact, you can think of properties as simply the “child” variables contained in an object.

Here are some examples of ActionScript code that uses properties. This line of code moves the MovieClip named square to the x coordinate 100 pixels:

square.x = 100;

This code uses the rotation property to make the square MovieClip rotate to match the rotation of the triangle MovieClip:

square.rotation = triangle.rotation;

This code alters the horizontal scale of the square MovieClip making it one-and-a-half times wider than it used to be:

square.scaleX = 1.5;

Notice the common structure: you use a variable ( square , triangle ) as the name of the object, followed by a period ( . ) and then the name of the property ( x , rotation , scaleX ). The period, known as the dot operator , is used to indicate that you’re accessing one of the child elements of an object. The whole structure together, “variable name-dot-property name,” is used like a single variable, as a name for a single value in the computer’s memory.

A method is an action that an object can perform. For example, suppose you’ve made a movie clip symbol in Flash Professional with several keyframes and animation on its timeline. That movie clip can play, or stop, or be instructed to move the playhead to a particular frame.

This code instructs the MovieClip named shortFilm to start playing:

shortFilm.play();

This line makes the MovieClip named shortFilm stop playing (the playhead stops in place, like pausing a video):

shortFilm.stop();

This code makes a MovieClip named shortFilm move its playhead to Frame 1 and stop playing (like rewinding a video):

shortFilm.gotoAndStop(1);

Methods, like properties, are accessed by writing the object’s name (a variable), then a period, and then the name of the method followed by parentheses. The parentheses are the way that you indicate that you are calling the method, or in other words, instructing the object to perform that action. Sometimes values (or variables) are placed in the parentheses, as a way to pass along additional information that is necessary to carry out the action. These values are known as method parameters . For example, the gotoAndStop() method needs information about which frame to go to, so it requires a single parameter in the parentheses. Other methods, like play() and stop() , are self-explanatory, so they don’t require extra information. Nevertheless, they are still written with parentheses.

Unlike properties (and variables), methods aren’t used as value placeholders. However, some methods can perform calculations and return a result that can be used like a variable. For example, the Number class’s toString() method converts the numeric value to its text representation:

var numericData:Number = 9; 
var textData:String = numericData.toString();

For example, you would use the toString() method if you wanted to display the value of a Number variable in a text field on the screen. The TextField class’s text property is defined as a String, so it can contain only text values. (The text property represents the actual text content displayed on the screen). This line of code converts the numeric value in the variable numericData to text. It then makes the value show up on the screen in the TextField object named calculatorDisplay :

calculatorDisplay.text = numericData.toString();

A computer program is a series of instructions that the computer carries out step-by-step. Some simple computer programs consist of nothing more than a few steps that the computer performs, at which point the program ends. However, ActionScript programs are designed to keep running, waiting for user input or other things to happen. Events are the mechanism that determines which instructions the computer carries out and when.

In essence, events are things that happen that ActionScript is aware of and can respond to. Many events are related to user interaction, such as a user clicking a button or pressing a key on the keyboard. There are also other types of events. For example, if you use ActionScript to load an external image, there is an event that can let you know when the image has finished loading. When an ActionScript program is running, conceptually it just sits and waits for certain things to happen. When those things happen, the specific ActionScript code that you’ve specified for those events runs.

Before you can use an object in ActionScript, the object has to exist in the first place. One part of creating an object is declaring a variable; however, declaring a variable only creates an empty place in the computer’s memory. Always assign an actual value to the variable (create an object and store it in the variable) before you attempt to use or manipulate it. The process of creating an object is known as instantiating the object. In other words, you create an instance of a particular class.

One simple way to create an object instance doesn’t involve ActionScript at all. In Flash Professional place a movie clip symbol, button symbol, or text field on the Stage and assign it an instance name. Flash Professional automatically declares a variable with that instance name, creates an object instance, and stores that object in the variable. Similarly, in Flex you create a component in MXML either by coding an MXML tag or by placing the component on the editor in Flash Builder Design mode. When you assign an ID to that component, that ID becomes the name of an ActionScript variable containing that component instance.

However, you don’t always want to create an object visually, and for non-visual objects you can’t. There are several additional ways you can create object instances using only ActionScript.

With several ActionScript data types, you can create an instance using a literal expression , which is a value written directly into the ActionScript code. Here are some examples:

• Literal numeric value (enter the number directly):

  var someNumber:Number = 17.239; 
  var someNegativeInteger:int = -53; 
  var someUint:uint = 22;

• Literal String value (surround the text with double quotation marks):

  var firstName:String = "George"; 
  var soliloquy:String = "To be or not to be, that is the question...";

• Literal Boolean value (use the literal values true or false ):

  var niceWeather:Boolean = true; 
  var playingOutside:Boolean = false;

• Literal Array value (wrap a comma-separated list of values in square brackets):

  var seasons:Array = ["spring", "summer", "autumn", "winter"];

• Literal XML value (enter the XML directly):

  var employee:XML = <employee> 
          <firstName>Harold</firstName> 
          <lastName>Webster</lastName> 
      </employee>;

ActionScript also defines literal expressions for the Array, RegExp, Object, and Function data types.

The most common way to create an instance for any data type is to use the new operator with the class name, as shown here:

var raceCar:MovieClip = new MovieClip(); 
var birthday:Date = new Date(2006, 7, 9);

Creating an object using the new operator is often described as “calling the class’s constructor.” A constructor is a special method that is called as part of the process of creating an instance of a class. Notice that when you create an instance in this way, you put parentheses after the class name. Sometimes you specify parameter values in the parentheses. These are two things that you also do when calling a method.

Even for those data types that let you create instances using a literal expression, you can also use the new operator to create an object instance. For example, these two lines of code do the same thing:

var someNumber:Number = 6.33; 
var someNumber:Number = new Number(6.33);

It’s important to be familiar with the new ClassName () way of creating objects. Many ActionScript data types don’t have a visual representation. Consequently, they can’t be created by placing an item on the Flash Professional Stage or the Design mode of Flash Builder’s MXML editor. You can only create an instance of any of those data types in ActionScript using the new operator.

You can think of events as occurrences of any kind in your SWF file that are of interest to you as a programmer. For example, most SWF files support user interaction of some sort—whether it's something as simple as responding to a mouse click or something more complex, such as accepting and processing data entered into a form. Any such user interaction with your SWF file is considered an event. Events can also occur without any direct user interaction, such as when data has finished loading from a server or when an attached camera has become active.

In ActionScript 3.0, each event is represented by an event object, which is an instance of the Event class or one of its subclasses. An event object not only stores information about a specific event, but also contains methods that facilitate manipulation of the event object. For example, when Flash Player or AIR detects a mouse click, it creates an event object (an instance of the MouseEvent class) to represent that particular mouse click event.

After creating an event object, Flash Player or AIR dispatches it, which means that the event object is passed to the object that is the target of the event. An object that serves as the destination for a dispatched event object is called an event target . For example, when an attached camera becomes active, Flash Player dispatches an event object directly to the event target, which in this case is the object that represents the camera. If the event target is on the display list, however, the event object is passed down through the display list hierarchy until it reaches the event target. In some cases, the event object then “bubbles” back up the display list hierarchy along the same route. This traversal of the display list hierarchy is called the event flow .

You can “listen” for event objects in your code using event listeners. Event listeners are the functions or methods that you write to respond to specific events. To ensure that your program responds to events, you must add event listeners either to the event target or to any display list object that is part of an event object’s event flow.

Any time you write event listener code, it follows this basic structure (elements in bold are placeholders you’d fill in for your specific case):

function eventResponse(eventObject:EventType):void 
{ 
    // Actions performed in response to the event go here. 
} 
 
eventTarget.addEventListener(EventType.EVENT_NAME, eventResponse);

This code does two things. First, it defines a function, which is the way to specify the actions that will be performed in response to the event. Next, it calls the addEventListener() method of the source object, in essence “subscribing” the function to the specified event so that when the event happens, the function’s actions are carried out. When the event actually happens, the event target checks its list of all the functions and methods that are registered as event listeners. It then calls each one in turn, passing the event object as a parameter.

You need to alter four things in this code to create your own event listener. First, you must change the name of the function to the name you want to use (this must be changed in two places, where the code says eventResponse ). Second, you must specify the appropriate class name of the event object that is dispatched by the event you want to listen for ( EventType in the code), and you must specify the appropriate constant for the specific event ( EVENT_NAME in the listing). Third, you must call the addEventListener() method on the object that will dispatch the event ( eventTarget in this code). Optionally, you can change the name of the variable used as the function’s parameter ( eventObject in this code).

Flash Player or AIR dispatches event objects whenever an event occurs. If the event target is not on the display list, Flash Player or AIR dispatches the event object directly to the event target. For example, Flash Player dispatches the progress event object directly to a URLStream object. If the event target is on the display list, however, Flash Player dispatches the event object into the display list, and the event object travels through the display list to the event target.

The event flow describes how an event object moves through the display list. The display list is organized in a hierarchy that can be described as a tree. At the top of the display list hierarchy is the Stage, which is a special display object container that serves as the root of the display list. The Stage is represented by the flash.display.Stage class and can only be accessed through a display object. Every display object has a property named stage that refers to the Stage for that application.

When Flash Player or AIR dispatches an event object for a display list-related event, that event object makes a round-trip journey from the Stage to the target node . The DOM Events Specification defines the target node as the node representing the event target. In other words, the target node is the display list object where the event occurred. For example, if a user clicks on a display list object named child1 , Flash Player or AIR will dispatch an event object using child1 as the target node.

The event flow is conceptually divided into three parts. The first part is called the capture phase; this phase comprises all of the nodes from the Stage to the parent of the target node. The second part is called the target phase, which consists solely of the target node. The third part is called the bubbling phase. The bubbling phase comprises the nodes encountered on the return trip from the parent of the target node back to the Stage.

The names of the phases make more sense if you conceive of the display list as a vertical hierarchy with the Stage at the top, as shown in the following diagram:

If a user clicks on Child1 Node , Flash Player or AIR dispatches an event object into the event flow. As the following image shows, the object’s journey starts at Stage , moves down to Parent Node , then moves to Child1 Node, and then “bubbles” back up to Stage , moving through Parent Node again on its journey back to Stage .

In this example, the capture phase comprises Stage and Parent Node during the initial downward journey. The target phase comprises the time spent at Child1 Node . The bubbling phase comprises Parent Node and Stage as they are encountered during the upward journey back to the root node.

The event flow contributes to a more powerful event-handling system than that previously available to ActionScript programmers. In previous versions of ActionScript, the event flow does not exist, which means that event listeners can be added only to the object that generates the event. In ActionScript 3.0, you can add event listeners not only to a target node, but also to any node along the event flow.

The ability to add event listeners along the event flow is useful when a user interface component comprises more than one object. For example, a button object often contains a text object that serves as the button’s label. Without the ability to add a listener to the event flow, you would have to add a listener to both the button object and the text object to ensure that you receive notification about click events that occur anywhere on the button. The existence of the event flow, however, allows you to place a single event listener on the button object that handles click events that occur either on the text object or on the areas of the button object that are not obscured by the text object.

Not every event object, however, participates in all three phases of the event flow. Some types of events, such as the enterFrame and init event types, are dispatched directly to the target node and participate in neither the capture phase nor the bubbling phase. Other events may target objects that are not on the display list, such as events dispatched to an instance of the Socket class. These event objects will also flow directly to the target object, without participating in the capture and bubbling phases.

To find out how a particular event type behaves, you can either check the API documentation or examine the event object's properties. Examining the event object’s properties is described in the following section.

Event objects serve two main purposes in the new event-handling system. First, event objects represent actual events by storing information about specific events in a set of properties. Second, event objects contain a set of methods that allow you to manipulate event objects and affect the behavior of the event-handling system.

To facilitate access to these properties and methods, the Flash Player API defines an Event class that serves as the base class for all event objects. The Event class defines a fundamental set of properties and methods that are common to all event objects.

This section begins with a discussion of the Event class properties, continues with a description of the Event class methods, and concludes with an explanation of why subclasses of the Event class exist.

Event listeners, which are also called event handlers, are functions that Flash Player and AIR execute in response to specific events. Adding an event listener is a two-step process. First, you create a function or class method for Flash Player or AIR to execute in response to the event. This is sometimes called the listener function or the event handler function. Second, you use the addEventListener() method to register your listener function with the target of the event or any display list object that lies along the appropriate event flow.

Display objects that inherit their interaction model from the InteractiveObject class can respond to keyboard events by using event listeners. For example, you can place an event listener on the Stage to listen for and respond to keyboard input. In the following code, an event listener captures a key press, and the key name and key code properties are displayed:

function reportKeyDown(event:KeyboardEvent):void 
{ 
    trace("Key Pressed: " + String.fromCharCode(event.charCode) +         " (character code: " + event.charCode + ")"); 
} 
stage.addEventListener(KeyboardEvent.KEY_DOWN, reportKeyDown);

Some keys, such as the Ctrl key, generate events even though they have no glyph representation.

In the previous code example, the keyboard event listener captured keyboard input for the entire Stage. You can also write an event listener for a specific display object on the Stage; this event listener is triggered when the object has the focus.

In the following example, keystrokes are reflected in the Output panel only when the user types inside the TextField instance. Holding the Shift key down temporarily changes the border color of the TextField to red.

This code assumes there is a TextField instance named tf on the Stage.

tf.border = true; 
tf.type = "input"; 
tf.addEventListener(KeyboardEvent.KEY_DOWN,reportKeyDown); 
tf.addEventListener(KeyboardEvent.KEY_UP,reportKeyUp); 
 
function reportKeyDown(event:KeyboardEvent):void 
{ 
    trace("Key Pressed: " + String.fromCharCode(event.charCode) +         " (key code: " + event.keyCode + " character code: "         + event.charCode + ")"); 
    if (event.keyCode == Keyboard.SHIFT) tf.borderColor = 0xFF0000; 
} 
 
function reportKeyUp(event:KeyboardEvent):void 
{ 
    trace("Key Released: " + String.fromCharCode(event.charCode) +         " (key code: " + event.keyCode + " character code: " +         event.charCode + ")"); 
    if (event.keyCode == Keyboard.SHIFT) 
    { 
        tf.borderColor = 0x000000; 
    } 
}

The TextField class also reports a textInput event that you can listen for when a user enters text. For more information, see Capturing text input.

Mouse clicks create mouse events that can be used to trigger interactive functionality. You can add an event listener to the Stage to listen for mouse events that occur anywhere within the SWF file. You can also add event listeners to objects on the Stage that inherit from InteractiveObject (for example, Sprite or MovieClip); these listeners are triggered when the object is clicked.

As with keyboard events, mouse events bubble. In the following example, because square is a child of the Stage, the event dispatches both from the sprite square as well as from the Stage object when the square is clicked:

var square:Sprite = new Sprite(); 
square.graphics.beginFill(0xFF0000); 
square.graphics.drawRect(0,0,100,100); 
square.graphics.endFill(); 
square.addEventListener(MouseEvent.CLICK, reportClick); 
square.x = 
square.y = 50; 
addChild(square); 
 
stage.addEventListener(MouseEvent.CLICK, reportClick); 
 
function reportClick(event:MouseEvent):void 
{ 
    trace(event.currentTarget.toString() +         " dispatches MouseEvent. Local coords [" +         event.localX + "," + event.localY + "] Stage coords [" +         event.stageX + "," + event.stageY + "]"); 
}

In the previous example, notice that the mouse event contains positional information about the click. The localX and localY properties contain the location of the click on the lowest child in the display chain. For example, clicking at the top-left corner of square reports local coordinates of [0,0] because that is the registration point of square . Alternatively, the stageX and stageY properties refer to the global coordinates of the click on the Stage. The same click reports [50,50] for these coordinates, because square was moved to these coordinates. Both of these coordinate pairs can be useful depending on how you want to respond to user interaction.

The MouseEvent object also contains altKey , ctrlKey , and shiftKey Boolean properties. You can use these properties to check if the Alt, Ctrl, or Shift key is also being pressed at the time of the mouse click.

Many APIs that load external data use the URLRequest class to define the properties of necessary network request.

The URLLoader class let you send a request to a server and access the information returned. You can also use the URLLoader class to access files on the local file system in contexts where local file access is permitted (such as the Flash Player local-with-filesystem sandbox and the AIR application sandbox). The URLLoader class downloads data from a URL as text, binary data, or URL-encoded variables. The URLLoader class dispatches events such as complete , httpStatus , ioError , open , progress , and securityError .

The ActionScript 3.0 event-handling model is significantly different than the ActionScript 2.0 model, which used the LoadVars.onData , LoadVars.onHTTPStatus , and LoadVars.onLoad event handlers. For more information on handling events in ActionScript 3.0, see Handling events

Downloaded data is not available until the download has completed. You can monitor the progress of the download (bytes loaded and bytes total) by listening for the progress event to be dispatched. However, if a file loads quickly enough a progress event might not be dispatched. When a file has successfully downloaded, the complete event is dispatched. By setting the URLLoader dataFormat property, you can receive the data as text, raw binary data, or as a URLVariables object.

The URLLoader.load() method (and optionally the URLLoader class’s constructor) takes a single parameter, request , which is a URLRequest object. A URLRequest object contains all of the information for a single HTTP request, such as the target URL, request method ( GET or POST ), additional header information, and the MIME type.

For example, to upload an XML packet to a server-side script, you could use the following code:

var secondsUTC:Number = new Date().time; 
var dataXML:XML =  
    <clock> 
        <time>{secondsUTC}</time> 
    </clock>; 
var request:URLRequest = new URLRequest("http://www.yourdomain.com/time.cfm"); 
request.contentType = "text/xml"; 
request.data = dataXML.toXMLString(); 
request.method = URLRequestMethod.POST; 
var loader:URLLoader = new URLLoader(); 
loader.load(request); 

The previous snippet creates an XML document named dataXML that contains the XML packet to be sent to the server. The example sets the URLRequest contentType property to "text/xml" and assigns the XML document to the URLRequest data property. Finally, the example creates a URLLoader object and sends the request to the remote script by using the load() method.

The URLStream class provides access to the downloading data as the data arrives. The URLStream class also lets you close a stream before it finishes downloading. The downloaded data is available as raw binary data.

When reading data from a URLStream object, use the bytesAvailable property to determine whether sufficient data is available before reading it. An EOFError exception is thrown if you attempt to read more data than is available.

When you build dynamic applications, it can be useful to load data from external files or from server-side scripts. This lets you build dynamic applications without having to edit or recompile your application. For example, if you build a “tip of the day” application, you can write a server-side script that retrieves a random tip from a database and saves it to a text file once a day. Then your application can load the contents of a static text file instead of querying the database each time.

The following snippet creates a URLRequest and URLLoader object, which loads the contents of an external text file, params.txt:

var request:URLRequest = new URLRequest("params.txt"); 
var loader:URLLoader = new URLLoader(); 
loader.load(request);

var request:URLRequest = new URLRequest("sendfeedback.cfm"); 
request.method = URLRequestMethod.POST;

The external document, params.txt, that is loaded at run time contains the following data:

monthNames=January,February,March,April,May,June,July,August,September,October,November,December&dayNames=Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday

The file contains two parameters, monthNames and dayNames . Each parameter contains a comma-separated list that is parsed as strings. You can split this list into an array using the String.split() method.

Avoid using reserved words or language constructs as variable names in external data files, because doing so makes reading and debugging your code more difficult.

function completeHandler(event) 
{ 
    var loader2 = event.target; 
    air.trace(loader2.data); 
}

If the remote document contains name-value pairs, you can parse the data using the URLVariables class by passing in the contents of the loaded file, as follows:

private function completeHandler(event:Event):void 
{ 
    var loader2:URLLoader = URLLoader(event.target); 
    var variables:URLVariables = new URLVariables(loader2.data); 
    trace(variables.dayNames); 
}

Each name-value pair from the external file is created as a property in the URLVariables object. Each property within the variables object in the previous code sample is treated as a string. If the value of the name-value pair is a list of items, you can convert the string into an array by calling the String.split() method, as follows:

var dayNameArray:Array = variables.dayNames.split(",");

If you are loading numeric data from external text files, convert the values into numeric values by using a top-level function, such as int() , uint() , or Number() .

Instead of loading the contents of the remote file as a string and creating a new URLVariables object, you could instead set the URLLoader.dataFormat property to one of the static properties found in the URLLoaderDataFormat class. The three possible values for the URLLoader.dataFormat property are as follows:

• URLLoaderDataFormat.BINARY —The URLLoader.data property will contain binary data stored in a ByteArray object.

• URLLoaderDataFormat.TEXT —The URLLoader.data property will contain text in a String object.

• URLLoaderDataFormat.VARIABLES —The URLLoader.data property will contain URL-encoded variables stored in a URLVariables object.

The following code demonstrates how setting the URLLoader.dataFormat property to URLLoaderDataFormat.VARIABLES allows you to automatically parse loaded data into a URLVariables object:

package 
{ 
    import flash.display.Sprite; 
    import flash.events.*; 
    import flash.net.URLLoader; 
    import flash.net.URLLoaderDataFormat; 
    import flash.net.URLRequest; 
 
    public class URLLoaderDataFormatExample extends Sprite 
    { 
        public function URLLoaderDataFormatExample() 
        { 
            var request:URLRequest = new URLRequest("http://www.[yourdomain].com/params.txt"); 
            var variables:URLLoader = new URLLoader(); 
            variables.dataFormat = URLLoaderDataFormat.VARIABLES; 
            variables.addEventListener(Event.COMPLETE, completeHandler); 
            try 
            { 
                variables.load(request); 
            }  
            catch (error:Error) 
            { 
                trace("Unable to load URL: " + error); 
            } 
        } 
        private function completeHandler(event:Event):void 
        { 
        var loader:URLLoader = URLLoader(event.target); 
        trace(loader.data.dayNames); 
        } 
    } 
}

As the following example shows, loading XML from an external file is the same as loading URLVariables. You can create a URLRequest instance and a URLLoader instance and use them to download a remote XML document. When the file has completely downloaded, the Event.COMPLETE event is dispatched and the contents of the external file are converted to an XML instance, which you can parse using XML methods and properties.

package 
{ 
    import flash.display.Sprite; 
    import flash.errors.*; 
    import flash.events.*; 
    import flash.net.URLLoader; 
    import flash.net.URLRequest; 
 
    public class ExternalDocs extends Sprite 
    { 
        public function ExternalDocs() 
        { 
            var request:URLRequest = new URLRequest("http://www.[yourdomain].com/data.xml"); 
            var loader:URLLoader = new URLLoader(); 
            loader.addEventListener(Event.COMPLETE, completeHandler); 
            try 
            { 
                loader.load(request); 
            } 
            catch (error:ArgumentError) 
            { 
                trace("An ArgumentError has occurred."); 
            } 
            catch (error:SecurityError) 
            { 
                trace("A SecurityError has occurred."); 
            } 
        } 
        private function completeHandler(event:Event):void 
        { 
            var dataXML:XML = XML(event.target.data); 
            trace(dataXML.toXMLString()); 
        } 
    } 
}

In addition to loading external data files, you can also use the URLVariables class to send variables to a server-side script and process the server’s response. This is useful, for example, if you are programming a game and want to send the user’s score to a server to calculate whether it should be added to the high scores list, or even send a user’s login information to a server for validation. A server-side script can process the user name and password, validate it against a database, and return confirmation of whether the user-supplied credentials are valid.

The following snippet creates a URLVariables object named variables, which creates a new variable called name . Next, a URLRequest object is created that specifies the URL of the server-side script to send the variables to. Then you set the method property of the URLRequest object to send the variables as an HTTP POST request. To add the URLVariables object to the URL request, you set the data property of the URLRequest object to the URLVariables object created earlier. Finally, the URLLoader instance is created and the URLLoader.load() method is invoked, which initiates the request.

var variables:URLVariables = new URLVariables("name=Franklin"); 
var request:URLRequest = new URLRequest(); 
request.url = "http://www.[yourdomain].com/greeting.cfm"; 
request.method = URLRequestMethod.POST; 
request.data = variables; 
var loader:URLLoader = new URLLoader(); 
loader.dataFormat = URLLoaderDataFormat.VARIABLES; 
loader.addEventListener(Event.COMPLETE, completeHandler); 
try 
{ 
    loader.load(request); 
} 
catch (error:Error) 
{ 
    trace("Unable to load URL"); 
} 
 
function completeHandler(event:Event):void 
{ 
    trace(event.target.data.welcomeMessage); 
}

The following code contains the contents of the Adobe ColdFusion® greeting.cfm document used in the previous example:

<cfif NOT IsDefined("Form.name") OR Len(Trim(Form.Name)) EQ 0> 
    <cfset Form.Name = "Stranger" /> 
</cfif> 
<cfoutput>welcomeMessage=#UrlEncodedFormat("Welcome, " & Form.name)# 
</cfoutput>

Loader objects are used to load SWF files and graphics files into an application. The Loader class is a subclass of the DisplayObjectContainer class. A Loader object can contain only one child display object in its display list—the display object representing the SWF or graphic file that it loads. When you add a Loader object to the display list, as in the following code, you also add the loaded child display object to the display list once it loads:

var pictLdr:Loader = new Loader(); 
var pictURL:String = "banana.jpg" 
var pictURLReq:URLRequest = new URLRequest(pictURL); 
pictLdr.load(pictURLReq); 
this.addChild(pictLdr);

Once the SWF file or image is loaded, you can move the loaded display object to another display object container, such as the container DisplayObjectContainer object in this example:

import flash.display.*; 
import flash.net.URLRequest; 
import flash.events.Event; 
var container:Sprite = new Sprite(); 
addChild(container); 
var pictLdr:Loader = new Loader(); 
var pictURL:String = "banana.jpg" 
var pictURLReq:URLRequest = new URLRequest(pictURL); 
pictLdr.load(pictURLReq); 
pictLdr.contentLoaderInfo.addEventListener(Event.COMPLETE, imgLoaded);  
function imgLoaded(event:Event):void 
{ 
    container.addChild(pictLdr.content);  
}

Once the file has started loading, a LoaderInfo object is created. A LoaderInfo object provides information such as load progress, the URLs of the loader and loadee, the number of bytes total for the media, and the nominal height and width of the media. A LoaderInfo object also dispatches events for monitoring the progress of the load.

The following diagram shows the different uses of the LoaderInfo object—for the instance of the main class of the SWF file, for a Loader object, and for an object loaded by the Loader object:

View full size graphic

The LoaderInfo object can be accessed as a property of both the Loader object and the loaded display object. As soon as loading begins, the LoaderInfo object can be accessed through the contentLoaderInfo property of the Loader object. Once the display object has finished loading, the LoaderInfo object can also be accessed as a property of the loaded display object through the display object’s loaderInfo property. The loaderInfo property of the loaded display object refers to the same LoaderInfo object as the contentLoaderInfo property of the Loader object. In other words, a LoaderInfo object is shared between a loaded object and the Loader object that loaded it (between loader and loadee).

In order to access properties of loaded content, you will want to add an event listener to the LoaderInfo object, as in the following code:

import flash.display.Loader; 
import flash.display.Sprite; 
import flash.events.Event; 
 
var ldr:Loader = new Loader(); 
var urlReq:URLRequest = new URLRequest("Circle.swf"); 
ldr.load(urlReq); 
ldr.contentLoaderInfo.addEventListener(Event.COMPLETE, loaded); 
addChild(ldr); 
 
function loaded(event:Event):void 
{ 
    var content:Sprite = event.target.content; 
    content.scaleX = 2; 
}

For more information, see Handling events.

When you load an external file into Flash Player or AIR through the load() or loadBytes() method of the Loader class, you can optionally specify a context parameter. This parameter is a LoaderContext object.

The LoaderContext class includes three properties that let you define the context of how the loaded content can be used:

• checkPolicyFile : Use this property only when loading an image file (not a SWF file). If you set this property to true , the Loader checks the origin server for a policy file (see Website controls (policy files)). This is necessary only for content originating from domains other than that of the SWF file containing the Loader object. If the server grants permission to the Loader domain, ActionScript from SWF files in the Loader domain can access data in the loaded image; in other words, you can use the BitmapData.draw() command to access data in the loaded image.

  Note that a SWF file from other domains than that of the Loader object can call Security.allowDomain() to permit a specific domain.

• securityDomain : Use this property only when loading a SWF file (not an image). Specify this for a SWF file from a domain other than that of the file containing the Loader object. When you specify this option, Flash Player checks for the existence of a policy file, and if one exists, SWF files from the domains permitted in the cross-policy file can cross-script the loaded SWF content. You can specify flash.system.SecurityDomain.currentDomain as this parameter.

• applicationDomain : Use this property only when loading a SWF file written in ActionScript 3.0 (not an image or a SWF file written in ActionScript 1.0 or 2.0). When loading the file, you can specify that the file be included in the same application domain as that of the Loader object, by setting the applicationDomain parameter to flash.system.ApplicationDomain.currentDomain . By putting the loaded SWF file in the same application domain, you can access its classes directly. This can be useful if you are loading a SWF file that contains embedded media, which you can access via their associated class names. For more information, see Working with application domains.

Here’s an example of checking for a policy file when loading a bitmap from another domain:

var context:LoaderContext = new LoaderContext(); 
context.checkPolicyFile = true; 
var urlReq:URLRequest = new URLRequest("http://www.[your_domain_here].com/photo11.jpg"); 
var ldr:Loader = new Loader(); 
ldr.load(urlReq, context);

Here’s an example of checking for a policy file when loading a SWF from another domain, in order to place the file in the same security sandbox as the Loader object. Additionally, the code adds the classes in the loaded SWF file to the same application domain as that of the Loader object:

var context:LoaderContext = new LoaderContext(); 
context.securityDomain = SecurityDomain.currentDomain; 
context.applicationDomain = ApplicationDomain.currentDomain; 
var urlReq:URLRequest = new URLRequest("http://www.[your_domain_here].com/library.swf"); 
var ldr:Loader = new Loader(); 
ldr.load(urlReq, context);

For more information, see the LoaderContext class in the ActionScript 3.0 Reference for the Adobe Flash Platform .

To help with remote shared library (RSL) preloading, Flash Professional CS5.5 introduces the fl.display.ProLoader and fl.display.ProLoaderInfo classes. These classes mirror the flash.display.Loader and flash.display.LoaderInfo classes but provide a more consistent loading experience.

In particular, ProLoader helps you load SWF files that use the Text Layout Framework (TLF) with RSL preloading. At runtime, SWF files that preload other SWF files or SWZ files, such as TLF, require an internal-only SWF wrapper file. The extra layer of complexity imposed by the SWF wrapper file can result in unwanted behavior. ProLoader solves this complexity to load these files as though they were ordinary SWF files. The solution used by the ProLoader class is transparent to the user and requires no special handling in ActionScript. In addition, ProLoader loads ordinary SWF content correctly.

In Flash Professional CS5.5 and later, you can safely replace all usages of the Loader class with the ProLoader class. Then, export your application to Flash Player 10.2 or higher so that ProLoader can access the required ActionScript functionality. You can also use ProLoader while targeting earlier versions of Flash Player that support ActionScript 3.0. However, you get full advantage of ProLoader features only with Flash Player 10.2 or higher. Always use ProLoader when you use TLF in Flash Professional CS5.5 or later. ProLoader is not needed in environments other than Flash Professional.

import flash.display.Loader; 
import flash.events.Event; 
var l:Loader = new Loader(); 
 
addChild(l); 
l.contentLoaderInfo.addEventListener(Event.COMPLETE, loadComplete); 
l.load("my.swf"); 
function loadComplete(e:Event) { 
    trace('load complete!'); 
}

import fl.display.ProLoader; 
import flash.events.Event; 
var l:ProLoader = new ProLoader(); 
 
addChild(l); 
l.contentLoaderInfo.addEventListener(Event.COMPLETE, loadComplete); 
l.load("my.swf"); 
function loadComplete(e:Event) { 
    trace('load complete!'); 
}

ActionScript 3.0 includes many tools for error handling, including:

• Error classes. ActionScript 3.0 includes a broad range of Error classes to expand the scope of situations that can produce error objects. Each Error class helps applications handle and respond to specific error conditions, whether they are related to system errors (like a MemoryError condition), coding errors (like an ArgumentError condition), networking and communication errors (like a URIError condition), or other situations. For more information on each class, see Comparing the Error classes.

• Fewer silent failures. In earlier versions of Flash Player, errors were generated and reported only if you explicitly used the throw statement. For Flash Player 9 and later Flash runtimes, native ActionScript methods and properties throw run-time errors. These errors allow you to handle these exceptions more effectively when they occur, then react to each exception, individually.

• Clear error messages displayed during debugging. When you are using the debugger version of a Flash runtime, problematic code or situations generate robust error messages, which help you easily identify reasons why a particular block of code fails. These messages make fixing errors more efficient. For more information, see Working with the debugger versions of Flash runtimes.

• Precise errors allow for clear error messages displayed to users. In previous versions of Flash Player, the FileReference.upload() method returned a Boolean value of false if the upload() call was unsuccessful, indicating one of five possible errors. If an error occurs when you call the upload() method in ActionScript 3.0, four specific errors help you display more accurate error messages to end users.

• Refined error handling. Distinct errors are thrown for many common situations. For example, in ActionScript 2.0, before a FileReference object has been populated, the name property has the value null (so, before you can use or display the name property, ensure that the value is set and not null ). In ActionScript 3.0, if you attempt to access the name property before it has been populated, Flash Player or AIR throws an IllegalOperationError, which informs you that the value has not been set, and you can use try..catch..finally blocks to handle the error. For more information see Using try..catch..finally statements.

• No significant performance drawbacks. Using try..catch..finally blocks to handle errors takes little or no additional resources compared to previous versions of ActionScript.

• An ErrorEvent class that allows you to build listeners for specific asynchronous error events. For more information see Responding to error events and status.

As long as your application doesn’t encounter a problematic condition, it can still run successfully if you don’t build error-handling logic into your code. However, if you don’t actively handle errors and your application does encounter a problem, your users will never know why your application fails when it does.

There are different ways you can approach error handling in your application. The following list summarizes the three major options for handling errors:

• Use try..catch..finally statements. These statements catch synchronous errors as they occur. You can nest your statements into a hierarchy to catch exceptions at various levels of code execution. For more information, see Using try..catch..finally statements.

• Create your own custom error objects. You can use the Error class to create your own custom error objects to track specific operations in your application that are not covered by built-in error types. Then you can use try..catch..finally statements on your custom error objects. For more information see Creating custom error classes.

• Write event listeners and handlers to respond to error events. By using this strategy, you can create global error handlers that let you handle similar events without duplicating much code in try..catch..finally blocks. You are also more likely to catch asynchronous errors using this approach. For more information, see Responding to error events and status.

When you work with synchronous run-time errors, use the try..catch..finally statements to catch errors. When a run-time error occurs, the Flash runtime throws an exception, which means that it suspends normal execution and creates a special object of type Error. The Error object is then thrown to the first available catch block.

The try statement encloses statements that have the potential to create errors. You always use the catch statement with a try statement. If an error is detected in one of the statements in the try statement block, the catch statements that are attached to that try statement run.

The finally statement encloses statements that run whether an error occurs in the try block. If there is no error, the statements within the finally block execute after the try block statements complete. If there is an error, the appropriate catch statement executes first, followed by the statements in the finally block.

The following code demonstrates the syntax for using the try..catch..finally statements:

try 
{ 
    // some code that could throw an error 
} 
catch (err:Error) 
{ 
    // code to react to the error 
} 
finally 
{ 
    // Code that runs whether an error was thrown. This code can clean 
    // up after the error, or take steps to keep the application running. 
}

Each catch statement identifies a specific type of exception that it handles. The catch statement can specify only error classes that are subclasses of the Error class. Each catch statement is checked in order. Only the first catch statement that matches the type of error thrown runs. In other words, if you first check the higher-level Error class and then a subclass of the Error class, only the higher-level Error class matches. The following code illustrates this point:

try 
{ 
    throw new ArgumentError("I am an ArgumentError"); 
} 
catch (error:Error) 
{ 
    trace("<Error> " + error.message); 
} 
catch (error:ArgumentError) 
{ 
    trace("<ArgumentError> " + error.message); 
}

The previous code displays the following output:

<Error> I am an ArgumentError

To correctly catch the ArgumentError, make sure that the most specific error types are listed first and the more generic error types are listed later, as the following code shows:

try 
{ 
    throw new ArgumentError("I am an ArgumentError"); 
} 
catch (error:ArgumentError) 
{ 
    trace("<ArgumentError> " + error.message); 
} 
catch (error:Error) 
{ 
    trace("<Error> " + error.message); 
}

Several methods and properties in the ActionScript API throw run-time errors if they encounter errors while they execute. For example, the close() method in the Sound class throws an IOError if the method is unable to close the audio stream, as demonstrated in the following code:

var mySound:Sound = new Sound(); 
try 
{ 
    mySound.close(); 
} 
catch (error:IOError) 
{ 
    // Error #2029: This URLStream object does not have an open stream. 
}

As you become more familiar with the ActionScript 3.0 Reference for the Adobe Flash Platform , you’ll notice which methods throw exceptions, as detailed in each method’s description.

Flash runtimes throw exceptions when they encounter errors in your running application. In addition, you can explicitly throw exceptions yourself using the throw statement. When explicitly throwing errors, Adobe recommends that you throw instances of the Error class or its subclasses. The following code demonstrates a throw statement that throws an instance of the Error class, MyErr , and eventually calls a function, myFunction() , to respond after the error is thrown:

var MyError:Error = new Error("Encountered an error with the numUsers value", 99); 
var numUsers:uint = 0; 
try 
{ 
    if (numUsers == 0) 
    { 
        trace("numUsers equals 0"); 
    } 
} 
catch (error:uint) 
{ 
    throw MyError; // Catch unsigned integer errors. 
} 
catch (error:int) 
{ 
    throw MyError; // Catch integer errors. 
} 
catch (error:Number) 
{ 
    throw MyError; // Catch number errors. 
} 
catch (error:*) 
{ 
    throw MyError; // Catch any other error. 
} 
finally  
{ 
    myFunction(); // Perform any necessary cleanup here. 
}

Notice that the catch statements are ordered so that the most specific data types are listed first. If the catch statement for the Number data type is listed first, neither the catch statement for the uint data type nor the catch statement for the int data type is ever run.

One of the biggest benefits of the new exception and error event model is that it allows you to tell users when and why an action has failed. Your part is to write the code to display the message and offer options in response.

The following code shows a simple try..catch statement to display the error in a text field:

package 
{ 
    import flash.display.Sprite; 
    import flash.text.TextField; 
     
    public class SimpleError extends Sprite 
    { 
        public var employee:XML =  
            <EmpCode> 
                <costCenter>1234</costCenter> 
                <costCenter>1-234</costCenter> 
            </EmpCode>; 
 
        public function SimpleError() 
        { 
            try 
            { 
                if (employee.costCenter.length() != 1) 
                { 
                    throw new Error("Error, employee must have exactly one cost center assigned."); 
                } 
            }  
            catch (error:Error) 
            { 
                var errorMessage:TextField = new TextField(); 
                errorMessage.autoSize = TextFieldAutoSize.LEFT; 
                errorMessage.textColor = 0xFF0000; 
                errorMessage.text = error.message; 
                addChild(errorMessage); 
            } 
        } 
    } 
}

Using a wider range of error classes and built-in compiler errors, ActionScript 3.0 offers more information than previous versions of ActionScript about why something has failed. This information enables you to build more stable applications with better error handling.

When you build applications, there are several occasions in which you need to rethrow an error if you are unable to handle the error properly. For example, the following code shows a nested try..catch block, which rethrows a custom ApplicationError if the nested catch block is unable to handle the error:

try 
{ 
    try 
    { 
        trace("<< try >>"); 
        throw new ApplicationError("some error which will be rethrown"); 
    } 
    catch (error:ApplicationError) 
    { 
        trace("<< catch >> " + error); 
        trace("<< throw >>"); 
        throw error; 
    } 
    catch (error:Error) 
    { 
        trace("<< Error >> " + error); 
    } 
} 
catch (error:ApplicationError) 
{ 
    trace("<< catch >> " + error); 
}

The output from the previous snippet would be the following:

<< try >> 
<< catch >> ApplicationError: some error which will be rethrown 
<< throw >> 
<< catch >> ApplicationError: some error which will be rethrown

The nested try block throws a custom ApplicationError error that is caught by the subsequent catch block. This nested catch block can try to handle the error, and if unsuccessful, throw the ApplicationError object to the enclosing try..catch block.

The ErrorEvent class and its subclasses contain error types for handling errors dispatched by Flash runtimes as they try to read or write data.

The following example uses both a try..catch statement and error event handlers to display any errors detected while trying to read a local file. You can add more sophisticated handling code to provide a user with options or otherwise handle the error automatically in the places indicated by the comment “your error-handling code here”:

package 
{ 
    import flash.display.Sprite; 
    import flash.errors.IOError; 
    import flash.events.IOErrorEvent; 
    import flash.events.TextEvent; 
    import flash.media.Sound; 
    import flash.media.SoundChannel; 
    import flash.net.URLRequest; 
    import flash.text.TextField; 
    import flash.text.TextFieldAutoSize; 
 
    public class LinkEventExample extends Sprite 
    { 
        private var myMP3:Sound; 
        public function LinkEventExample() 
        { 
            myMP3 = new Sound(); 
            var list:TextField = new TextField(); 
            list.autoSize = TextFieldAutoSize.LEFT; 
            list.multiline = true; 
            list.htmlText = "<a href=\"event:track1.mp3\">Track 1</a><br>"; 
            list.htmlText += "<a href=\"event:track2.mp3\">Track 2</a><br>"; 
            addEventListener(TextEvent.LINK, linkHandler); 
            addChild(list); 
        } 
         
        private function playMP3(mp3:String):void 
        { 
            try 
            { 
                myMP3.load(new URLRequest(mp3)); 
                myMP3.play(); 
            } 
            catch (err:Error) 
            { 
                trace(err.message); 
                // your error-handling code here 
            } 
            myMP3.addEventListener(IOErrorEvent.IO_ERROR, errorHandler); 
        } 
 
        private function linkHandler(linkEvent:TextEvent):void 
        { 
            playMP3(linkEvent.text); 
            // your error-handling code here 
        } 
         
        private function errorHandler(errorEvent:IOErrorEvent):void 
        { 
            trace(errorEvent.text); 
            // your error-handling code here 
        } 
    } 
}

Flash runtimes dynamically change the value of the netStatus.info.level or status.level properties for the classes that support the level property while an application is running. The classes that have the netStatus.info.level property are NetConnection, NetStream, and SharedObject. The classes that have the status.level property are HTTPStatusEvent, Camera, Microphone, and LocalConnection. You can write a handler function to respond to the change in level value and track communication errors.

The following example uses a netStatusHandler() function to test the value of the level property. If the level property indicates that an error has been encountered, the code traces the message “Video stream failed”.

package 
{ 
    import flash.display.Sprite; 
    import flash.events.NetStatusEvent; 
    import flash.events.SecurityErrorEvent; 
    import flash.media.Video; 
    import flash.net.NetConnection; 
    import flash.net.NetStream; 
 
    public class VideoExample extends Sprite 
    { 
        private var videoUrl:String = "Video.flv"; 
        private var connection:NetConnection; 
        private var stream:NetStream; 
 
        public function VideoExample() 
        { 
            connection = new NetConnection(); 
            connection.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler); 
            connection.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler); 
            connection.connect(null); 
        } 
 
        private function netStatusHandler(event:NetStatusEvent):void 
        { 
            if (event.info.level == "error") 
            { 
                trace("Video stream failed") 
            } 
            else  
            { 
                connectStream(); 
            } 
        } 
 
        private function securityErrorHandler(event:SecurityErrorEvent):void 
        { 
            trace("securityErrorHandler: " + event); 
        } 
 
        private function connectStream():void 
        { 
            var stream:NetStream = new NetStream(connection); 
            var video:Video = new Video(); 
            video.attachNetStream(stream); 
            stream.play(videoUrl); 
            addChild(video); 
        } 
    } 
}

The core error classes include the Error, ArgumentError, EvalError, RangeError, ReferenceError, SecurityError, SyntaxError, TypeError, URIError, and VerifyError classes. Each of these classes are located in the top-level namespace.

The flash.error package contains Error classes that are considered part of the Flash runtime API. In contrast to the Error classes described, the flash.error package communicates errors events that are specific to Flash runtimes (such as Flash Player and Adobe AIR).

There are two ways to create associative arrays in ActionScript 3.0. The first way is to use an Object instance. By using an Object instance you can initialize your array with an object literal. An instance of the Object class, also called a generic object , is functionally identical to an associative array. Each property name of the generic object serves as the key that provides access to a stored value.

The following example creates an associative array named monitorInfo , using an object literal to initialize the array with two key and value pairs:

var monitorInfo:Object = {type:"Flat Panel", resolution:"1600 x 1200"}; 
trace(monitorInfo["type"], monitorInfo["resolution"]);  
// output: Flat Panel 1600 x 1200

If you do not need to initialize the array at declaration time, you can use the Object constructor to create the array, as follows:

var monitorInfo:Object = new Object();

After the array is created using either an object literal or the Object class constructor, you can add new values to the array using either the array access ( [] ) operator or the dot operator ( . ). The following example adds two new values to monitorArray :

monitorInfo["aspect ratio"] = "16:10"; // bad form, do not use spaces 
monitorInfo.colors = "16.7 million"; 
trace(monitorInfo["aspect ratio"], monitorInfo.colors); 
// output: 16:10 16.7 million

Note that the key named aspect ratio contains a space character. This is possible with the array access ( [] ) operator, but generates an error if attempted with the dot operator. Using spaces in your key names is not recommended.

The second way to create an associative array is to use the Array constructor (or the constructor of any dynamic class) and then use either the array access ( [] ) operator or the dot operator ( . ) to add key and value pairs to the array. If you declare your associative array to be of type Array, you cannot use an object literal to initialize the array. The following example creates an associative array named monitorInfo using the Array constructor and adds a key called type and a key called resolution , along with their values:

var monitorInfo:Array = new Array(); 
monitorInfo["type"] = "Flat Panel"; 
monitorInfo["resolution"] = "1600 x 1200"; 
trace(monitorInfo["type"], monitorInfo["resolution"]);  
// output: Flat Panel 1600 x 1200

There is no advantage in using the Array constructor to create an associative array. You cannot use the Array.length property or any of the methods of the Array class with associative arrays, even if you use the Array constructor or the Array data type. The use of the Array constructor is best left for the creation of indexed arrays.

You can use the Dictionary class to create an associative array that uses objects for keys rather than strings. Such arrays are sometimes called dictionaries, hashes, or maps. For example, consider an application that determines the location of a Sprite object based on its association with a specific container. You can use a Dictionary object to map each Sprite object to a container.

The following code creates three instances of the Sprite class that serve as keys for the Dictionary object. Each key is assigned a value of either GroupA or GroupB . The values can be of any data type, but in this example both GroupA and GroupB are instances of the Object class. Subsequently, you can access the value associated with each key with the array access ( [] ) operator, as shown in the following code:

import flash.display.Sprite; 
import flash.utils.Dictionary; 
 
var groupMap:Dictionary = new Dictionary(); 
 
// objects to use as keys 
var spr1:Sprite = new Sprite(); 
var spr2:Sprite = new Sprite(); 
var spr3:Sprite = new Sprite(); 
 
// objects to use as values 
var groupA:Object = new Object(); 
var groupB:Object = new Object(); 
 
// Create new key-value pairs in dictionary. 
groupMap[spr1] = groupA; 
groupMap[spr2] = groupB; 
groupMap[spr3] = groupB; 
 
if (groupMap[spr1] == groupA) 
{ 
    trace("spr1 is in groupA");  
} 
if (groupMap[spr2] == groupB) 
{ 
    trace("spr2 is in groupB");  
} 
if (groupMap[spr3] == groupB) 
{ 
    trace("spr3 is in groupB");  
}

for (var key:Object in groupMap) 
{ 
    trace(key, groupMap[key]); 
} 
/* output: 
[object Sprite] [object Object] 
[object Sprite] [object Object] 
[object Sprite] [object Object] 
*/

for each (var item:Object in groupMap) 
{ 
    trace(item); 
} 
/* output: 
[object Object] 
[object Object] 
[object Object] 
*/

var myObject:Object = new Object();

import flash.utils.Dictionary; 
 
var myObject:Object = new Object(); 
var myMap:Dictionary = new Dictionary(); 
myMap[myObject] = "foo";

myObject = null; 
delete myMap[myObject];

import flash.utils.Dictionary; 
 
var myObject:Object = new Object(); 
var myMap:Dictionary = new Dictionary(true); 
myMap[myObject] = "foo"; 
myObject = null; // Make object eligible for garbage collection.

When you use two indexed arrays, you can visualize the result as a table or spreadsheet. The elements of the first array represent the rows of the table, while the elements of the second array represent the columns.

For example, the following multidimensional array uses two indexed arrays to track task lists for each day of the week. The first array, masterTaskList , is created using the Array class constructor. Each element of the array represents a day of the week, with index 0 representing Monday, and index 6 representing Sunday. These elements can be thought of as the rows in the table. You can create each day’s task list by assigning an array literal to each of the seven elements that you create in the masterTaskList array. The array literals represent the columns in the table.

var masterTaskList:Array = new Array(); 
masterTaskList[0] = ["wash dishes", "take out trash"]; 
masterTaskList[1] = ["wash dishes", "pay bills"]; 
masterTaskList[2] = ["wash dishes", "dentist", "wash dog"]; 
masterTaskList[3] = ["wash dishes"]; 
masterTaskList[4] = ["wash dishes", "clean house"]; 
masterTaskList[5] = ["wash dishes", "wash car", "pay rent"]; 
masterTaskList[6] = ["mow lawn", "fix chair"];

You can access individual items on any of the task lists using the array access ( [] ) operator. The first set of brackets represents the day of the week, and the second set of brackets represents the task list for that day. For example, to retrieve the second task from Wednesday’s list, first use index 2 for Wednesday, and then use index 1 for the second task in the list.

trace(masterTaskList[2][1]); // output: dentist

To retrieve the first task from Sunday’s list, use index 6 for Sunday and index 0 for the first task on the list.

trace(masterTaskList[6][0]); // output: mow lawn

To make the individual arrays easier to access, you can use an associative array for the days of the week and an indexed array for the task lists. Using an associative array allows you to use dot syntax when referring to a particular day of the week, but at the cost of extra run-time processing to access each element of the associative array. The following example uses an associative array as the basis of a task list, with a key and value pair for each day of the week:

var masterTaskList:Object = new Object(); 
masterTaskList["Monday"] = ["wash dishes", "take out trash"]; 
masterTaskList["Tuesday"] = ["wash dishes", "pay bills"]; 
masterTaskList["Wednesday"] = ["wash dishes", "dentist", "wash dog"]; 
masterTaskList["Thursday"] = ["wash dishes"]; 
masterTaskList["Friday"] = ["wash dishes", "clean house"]; 
masterTaskList["Saturday"] = ["wash dishes", "wash car", "pay rent"]; 
masterTaskList["Sunday"] = ["mow lawn", "fix chair"];

Dot syntax makes the code more readable by making it possible to avoid multiple sets of brackets.

trace(masterTaskList.Wednesday[1]); // output: dentist 
trace(masterTaskList.Sunday[0]);// output: mow lawn

You can iterate through the task list using a for..in loop, but you must use the array access ( [] ) operator instead of dot syntax to access the value associated with each key. Because masterTaskList is an associative array, the elements are not necessarily retrieved in the order that you may expect, as the following example shows:

for (var day:String in masterTaskList) 
{ 
    trace(day + ": " + masterTaskList[day]) 
} 
/* output: 
Sunday: mow lawn,fix chair 
Wednesday: wash dishes,dentist,wash dog 
Friday: wash dishes,clean house 
Thursday: wash dishes 
Monday: wash dishes,take out trash 
Saturday: wash dishes,wash car,pay rent 
Tuesday: wash dishes,pay bills 
*/

XML is a standard way of representing structured information so that it is easy for computers to work with and reasonably easy for people to write and understand. XML is an abbreviation for eXtensible Markup Language. The XML standard is available at www.w3.org/XML/ .

XML offers a standard and convenient way to categorize data, to make it easier to read, access, and manipulate. XML uses a tree structure and tag structure that is similar to HTML. Here is a simple example of XML data:

<song> 
    <title>What you know?</title> 
    <artist>Steve and the flubberblubs</artist> 
    <year>1989</year> 
    <lastplayed>2006-10-17-08:31</lastplayed> 
</song>

XML data can also be more complex, with tags nested in other tags as well as attributes and other structural components. Here is a more complex example of XML data:

<album> 
    <title>Questions, unanswered</title> 
    <artist>Steve and the flubberblubs</artist> 
    <year>1989</year> 
    <tracks> 
        <song tracknumber="1" length="4:05"> 
            <title>What do you know?</title> 
            <artist>Steve and the flubberblubs</artist> 
            <lastplayed>2006-10-17-08:31</lastplayed> 
        </song> 
        <song tracknumber="2" length="3:45"> 
            <title>Who do you know?</title> 
            <artist>Steve and the flubberblubs</artist> 
            <lastplayed>2006-10-17-08:35</lastplayed> 
        </song> 
        <song tracknumber="3" length="5:14"> 
            <title>When do you know?</title> 
            <artist>Steve and the flubberblubs</artist> 
            <lastplayed>2006-10-17-08:39</lastplayed> 
        </song> 
        <song tracknumber="4" length="4:19"> 
            <title>Do you know?</title> 
            <artist>Steve and the flubberblubs</artist> 
            <lastplayed>2006-10-17-08:44</lastplayed> 
        </song> 
    </tracks> 
</album>

Notice that this XML document contains other complete XML structures within it (such as the song tags with their children). It also demonstrates other XML structures such as attributes ( tracknumber and length in the song tags), and tags that contain other tags rather than containing data (such as the tracks tag).

<song tracknumber="1" length="4:05"> 
    <title>What do you know?</title> 
    <artist>Steve and the flubberblubs</artist> 
    <mood>Happy</mood> 
    <lastplayed>2006-10-17-08:31</lastplayed> 
</song>

<title>

</title>

<lastplayed/>

<lastplayed></lastplayed>

<song length="4:19"></song>

The ECMAScript for XML specification defines a set of classes and functionality for working with XML data. These classes and functionality are known collectively as E4X. ActionScript 3.0 includes the following E4X classes: XML, XMLList, QName, and Namespace.

The methods, properties, and operators of the E4X classes are designed with the following goals:

• Simplicity—Where possible, E4X makes it easier to write and understand code for working with XML data.

• Consistency—The methods and reasoning behind E4X are internally consistent and consistent with other parts of ActionScript.

• Familiarity—You manipulate XML data with well-known operators, such as the dot ( . ) operator.

Here is an example of manipulating data with E4X:

var myXML:XML =  
    <order> 
        <item id='1'> 
            <menuName>burger</menuName> 
            <price>3.95</price> 
        </item> 
        <item id='2'> 
            <menuName>fries</menuName> 
            <price>1.45</price> 
        </item> 
    </order>

Often, your application will load XML data from an external source, such as a web service or a RSS feed. However, for clarity, the code examples provided here assign XML data as literals.

As the following code shows, E4X includes some intuitive operators, such as the dot ( . ) and attribute identifier ( @ ) operators, for accessing properties and attributes in the XML:

trace(myXML.item[0].menuName); // Output: burger 
trace(myXML.item.(@id==2).menuName); // Output: fries 
trace(myXML.item.(menuName=="burger").price); // Output: 3.95

Use the appendChild() method to assign a new child node to the XML, as the following snippet shows:

var newItem:XML =  
    <item id="3"> 
        <menuName>medium cola</menuName> 
        <price>1.25</price> 
    </item> 
 
myXML.appendChild(newItem);

Use the @ and . operators not only to read data, but also to assign data, as in the following:

myXML.item[0].menuName="regular burger"; 
myXML.item[1].menuName="small fries"; 
myXML.item[2].menuName="medium cola"; 
 
myXML.item.(menuName=="regular burger").@quantity = "2"; 
myXML.item.(menuName=="small fries").@quantity = "2"; 
myXML.item.(menuName=="medium cola").@quantity = "2";

Use a for loop to iterate through nodes of the XML, as follows:

var total:Number = 0; 
for each (var property:XML in myXML.item) 
{ 
    var q:int = Number(property.@quantity); 
    var p:Number = Number(property.price); 
    var itemTotal:Number = q * p; 
    total += itemTotal; 
    trace(q + " " + property.menuName + " $" + itemTotal.toFixed(2)) 
} 
trace("Total: $", total.toFixed(2));

An XML object may represent an XML element, attribute, comment, processing instruction, or text element.

An XML object is classified as having either simple content or complex content . An XML object that has child nodes is classified as having complex content. An XML object is said to have simple content if it is any one of the following: an attribute, a comment, a processing instruction, or a text node.

For example, the following XML object contains complex content, including a comment and a processing instruction:

XML.ignoreComments = false; 
XML.ignoreProcessingInstructions = false; 
var x1:XML =  
    <order> 
        <!--This is a comment. --> 
        <?PROC_INSTR sample ?> 
        <item id='1'> 
            <menuName>burger</menuName> 
            <price>3.95</price> 
        </item> 
        <item id='2'> 
            <menuName>fries</menuName> 
            <price>1.45</price> 
        </item> 
    </order>

As the following example shows, you can now use the comments() and processingInstructions() methods to create new XML objects, a comment and a processing instruction:

var x2:XML = x1.comments()[0]; 
var x3:XML = x1.processingInstructions()[0];

An XMLList instance represents an arbitrary collection of XML objects. It can contain full XML documents, XML fragments, or the results of an XML query.

The following methods allow you to work with the hierarchical structure of XMLList objects:

• child()

• children()

• descendants()

• elements()

• parent()

The following methods allow you to work with XMLList object attributes:

• attribute()

• attributes()

The following methods allow you to you work with XMLList properties:

• hasOwnProperty()

• propertyIsEnumerable()

The following methods are for working with and determining certain types of XML content:

• comments()

• hasComplexContent()

• hasSimpleContent()

• processingInstructions()

• text()

The following are for conversion to strings and for formatting the XMLList object:

• normalize()

• toString()

• toXMLString()

There are a few additional methods:

• contains()

• copy()

• length()

• valueOf()

For details on these methods, see the ActionScript 3.0 Reference for the Adobe Flash Platform .

For an XMLList object that contains exactly one XML element, you can use all properties and methods of the XML class, because an XMLList with one XML element is treated the same as an XML object. For example, in the following code, because doc.div is an XMLList object containing one element, you can use the appendChild() method from the XML class:

var doc:XML =  
        <body> 
            <div> 
                <p>Hello</p> 
            </div> 
        </body>; 
doc.div.appendChild(<p>World</p>);

For a list of XML properties and methods, see XML objects.

You can assign an XML literal to an XML object, as follows:

var myXML:XML =  
    <order> 
        <item id='1'> 
            <menuName>burger</menuName> 
            <price>3.95</price> 
        </item> 
        <item id='2'> 
            <menuName>fries</menuName> 
            <price>1.45</price> 
        </item> 
    </order>

As the following snippet shows, you can also use the new constructor to create an instance of an XML object from a string that contains XML data:

var str:String = "<order><item id='1'><menuName>burger</menuName>" 
                            + "<price>3.95</price></item></order>"; 
var myXML:XML = new XML(str);

If the XML data in the string is not well formed (for example, if a closing tag is missing), you will see a run-time error.

You can also pass data by reference (from other variables) into an XML object, as the following example shows:

var tagname:String = "item";  
var attributename:String = "id";  
var attributevalue:String = "5";  
var content:String = "Chicken";  
var x:XML = <{tagname} {attributename}={attributevalue}>{content}</{tagname}>;  
trace(x.toXMLString()) 
    // Output: <item id="5">Chicken</item>

To load XML data from a URL, use the URLLoader class, as the following example shows:

import flash.events.Event; 
import flash.net.URLLoader; 
import flash.net.URLRequest; 
 
var externalXML:XML; 
var loader:URLLoader = new URLLoader(); 
var request:URLRequest = new URLRequest("xmlFile.xml"); 
loader.load(request); 
loader.addEventListener(Event.COMPLETE, onComplete); 
 
function onComplete(event:Event):void 
{ 
    var loader:URLLoader = event.target as URLLoader; 
    if (loader != null) 
    { 
        externalXML = new XML(loader.data); 
        trace(externalXML.toXMLString()); 
    } 
    else 
    { 
        trace("loader is not a URLLoader!"); 
    } 
}

To read XML data from a socket connection, use the XMLSocket class. For more information, see the XMLSocket class in the ActionScript 3.0 Reference for the Adobe Flash Platform .

Use the prependChild() method or the appendChild() method to add a property to the beginning or end of an XML object’s list of properties, as the following example shows:

var x1:XML = <p>Line 1</p>  
var x2:XML = <p>Line 2</p>  
var x:XML = <body></body> 
x = x.appendChild(x1); 
x = x.appendChild(x2); 
x = x.prependChild(<p>Line 0</p>); 
    // x == <body><p>Line 0</p><p>Line 1</p><p>Line 2</p></body>

Use the insertChildBefore() method or the insertChildAfter() method to add a property before or after a specified property, as follows:

var x:XML =  
    <body> 
        <p>Paragraph 1</p>  
        <p>Paragraph 2</p> 
    </body> 
var newNode:XML = <p>Paragraph 1.5</p>  
x = x.insertChildAfter(x.p[0], newNode) 
x = x.insertChildBefore(x.p[2], <p>Paragraph 1.75</p>)

As the following example shows, you can also use curly brace operators ( { and } ) to pass data by reference (from other variables) when constructing XML objects:

var ids:Array = [121, 122, 123];  
var names:Array = [["Murphy","Pat"], ["Thibaut","Jean"], ["Smith","Vijay"]] 
var x:XML = new XML("<employeeList></employeeList>"); 
 
for (var i:int = 0; i < 3; i++) 
{ 
    var newnode:XML = new XML();  
    newnode = 
        <employee id={ids[i]}> 
            <last>{names[i][0]}</last> 
            <first>{names[i][1]}</first> 
        </employee>; 
 
    x = x.appendChild(newnode) 
}

You can assign properties and attributes to an XML object by using the = operator, as in the following:

var x:XML =  
    <employee> 
        <lastname>Smith</lastname> 
    </employee> 
x.firstname = "Jean"; 
x.@id = "239";

This sets the XML object x to the following:

<employee id="239"> 
    <lastname>Smith</lastname> 
    <firstname>Jean</firstname> 
</employee>

You can use the + and += operators to concatenate XMLList objects:

var x1:XML = <a>test1</a>  
var x2:XML = <b>test2</b>  
var xList:XMLList = x1 + x2; 
xList += <c>test3</c>

This sets the XMLList object xList to the following:

<a>test1</a> 
<b>test2</b> 
<c>test3</c>

One of the powerful features of XML is its ability to provide complex, nested data via a linear string of text characters. When you load data into an XML object, ActionScript parses the data and loads its hierarchical structure into memory (or it sends a run-time error if the XML data is not well formed).

The operators and methods of the XML and XMLList objects make it easy to traverse the structure of XML data.

Use the dot (.) operator and the descendent accessor (..) operator to access child properties of an XML object. Consider the following XML object:

var myXML:XML =  
    <order> 
        <book ISBN="0942407296"> 
            <title>Baking Extravagant Pastries with Kumquats</title> 
            <author> 
                <lastName>Contino</lastName> 
                <firstName>Chuck</firstName> 
            </author> 
            <pageCount>238</pageCount> 
        </book> 
        <book ISBN="0865436401"> 
            <title>Emu Care and Breeding</title> 
            <editor> 
                <lastName>Case</lastName> 
                <firstName>Justin</firstName> 
            </editor> 
            <pageCount>115</pageCount> 
        </book> 
    </order>

The object myXML.book is an XMLList object containing child properties of the myXML object that have the name book . These are two XML objects, matching the two book properties of the myXML object.