Availability

Flash 5

Synopsis

arguments[elem]
arguments.propertyName

Properties

callee

A reference to the function being executed.

length

The number of parameters passed to the function being executed.

Description

The Arguments object is stored in the local arguments variable of every function and is accessible only while a function is executing. Arguments is both an array and an object. As an array, arguments stores the values of the parameters passed to the currently executing function. For example, arguments[0] is the first passed parameter, arguments[1] is the second passed parameter, and so on. As an object, Arguments stores the callee property, which can be used to identify or invoke the current function.

See Also

Availability

Flash 5

Constructor

new Array()
new Array(len)
new Array(element0, element1, element2,...elementn)

Arguments

len

A non-negative integer specifying the size of the new array.

element0,...elementn

A list of one or more initial values to be assigned as elements of the array.

Properties

length

The number of elements in an array (including empty elements).

Methods

concat( )

Create a new array by appending additional elements to an existing array.

join( )

Convert an array to a string.

pop( )

Remove and return the last element of an array.

push( )

Add one or more elements to the end of an array.

reverse( )

Reverse the order of elements in an array.

shift( )

Remove and return the first element of an array.

slice( )

Create a new array using a subset of elements from an existing array.

sort( )

Sort the elements of an array according to the specified rule.

splice( )

Remove elements from, and/or add elements to, an array.

toString( )

Convert an array to a string of comma-separated element values.

unshift( )

Add one or more elements to the beginning of an array.

Description

Availability

Flash 5

Synopsis

array.concat(value1, value2, value3,...valuen)

Arguments

value1,...valuen

A list of expressions to be added to the end of array as new elements.

Returns

A new array containing all the elements of array followed by the elements value1,...valuen.

Description

The concat( ) method returns a new array created by appending new elements to the end of an existing array. The original array is left unchanged. Use the push( ), splice( ), or shift( ) method to modify the original array.

If an array is used as an argument to concat( ), each element of that array is appended separately. That is, the result of arrayX.concat(arrayY) will be an array formed by appending each element of arrayY to the end of arrayX. The resulting array will have a length equal to arrayY.length + arrayX.length. Nested arrays, however, are not similarly flattened.

Example

// Create an array
myListA = new Array("apples", "oranges");

// Set myListB to ["apples", "oranges", "bananas"]
myListB = myListA.concat("bananas");     

// Create another new array
myListC = new Array("grapes", "plums");

// Set myListD to ["apples", "oranges", "bananas", "grapes", "plums"]
myListD = myListB.concat(myListC);

// Set myListA to ["apples", "oranges", "bananas"]
myListA = myListA.concat("bananas");

// Create an array
settings  = ["on", "off"];
// Append an array containing a nested array
options = settings.concat(["brightness", ["high", "medium", "low"]]);
// Sets options to: ["on", "off", "brightness", ["high", "medium", "low"]] 
// not: ["on", "off", "brightness", "high", "medium", "low"]

See Also

Availability

Flash 5

Synopsis

array.join()
array.join(delimiter)

Arguments

delimiter

An optional string to be placed between elements in the newly created string. Defaults to a comma if not supplied.

Returns

A string composed of all the elements of array converted to strings and separated by delimiter.

Description

The join( ) method returns a string created by combining all the elements of an array, as follows:

1. Convert each element in the array to a string (empty elements are converted to the empty string).

2. Add delimiter to the end of each converted-element string, except the last one.

3. Concatenate the converted-element strings into one long string.

Note that elements that are themselves arrays are converted to strings via the toString( ) method, so nested array elements are always delimited by commas, not the delimiter used in the join( ) invocation.

Example

fruit = new Array("apples","oranges","bananas","grapes","plums");
// Set fruitString to "apples,oranges,bananas,grapes,plums"
fruitString = fruit.join( );
// Set fruitString to "apples-oranges-bananas-grapes-plums"
fruitString = fruit.join("-");

See Also

Availability

Flash 5

Synopsis

array.length

Access

Read/write

Description

The length property is a non-negative integer specifying the number of elements in an array. An array with no elements has a length of 0, an array with 2 elements has a length of 2. Note that the index number of the first element in an array is 0, so length is always one greater than the index of the last element in the array.

The length property of an array indicates how many numbered elements the array currently contains, including empty elements (those containing null or undefined). For example, an array may have values for elements 0, 1, 2, and 9, but elements 3 through 8 may be empty. Such an array has a length of 10 because it has 10 element positions (0 through 9) even though only 4 positions are occupied by useful values.

Setting the length of an array changes the number of elements in the array. If we increase length, empty elements are added to the end of the array; if we decrease length, existing elements are removed from the end of the array. The length property changes automatically whenever any elements are added or removed via the Array class methods. The length property reflects numbered elements only; it does not include named array elements, which are treated as properties of the array.

Example

myList = new Array("one", "two", "three");
trace(myList.length);  // Displays: 3

// Loop through the array's elements
for (var i = 0; i < myList.length; i++) {
  trace(myList[i]);
}

See Also

Availability

Flash 5

Synopsis

array.pop()

Returns

The value of the last element of array, which is also deleted.

Description

The pop( ) method deletes the last element of an array, reduces the array's length by 1, and returns the value of the deleted element. Compare with the shift( ) method, which deletes the first element of an array.

Example

myList = new Array("one", "two", "three");
trace ("Now deleting " + myList.pop( ));  // myList is now: ["one", "two"]

See Also

Availability

Flash 5

Synopsis

array.push(value1, value2,...valuen)

Arguments

value1,...valuen

A list of one or more values to be added to the end of array.

Returns

The new length of array.

Description

The push( ) method appends a list of values to the end of an array as new elements. Elements are added in the order provided. It differs from concat( ) in that push( ) modifies the original array, whereas concat( ) creates a new array. It differs from unshift( ) in that it adds elements at the end of an array, not the beginning.

Example

myList = new Array (5, 6);
myList.push(7);             // myList is now [5, 6, 7]
myList.push(10, 8, 9);      // myList is now [5, 6, 7, 10, 8, 9]

See Also

Availability

Flash 5

Synopsis

array.shift()

Returns

The value of the first element of array, which is also deleted.

Description

The shift( ) method deletes the first element of an array and then moves all the remaining elements of the array up one position. The affected array's length is reduced by 1. Note that shift( ) differs from the pop( ) method, which deletes the last element of an array.

Example

myList = new Array ("a", "b", "c");
myList.shift( );                                  // myList becomes ["b", "c"]

See Also

Availability

Flash 5

Synopsis

array.slice(startIndex, endIndex)

Arguments

startIndex

A zero-relative integer specifying the first element in array to add to the new array. If negative, startIndex indicates an element number counting backward from the end of array (-1 is the last element, -2 is the second-to-last element, etc.).

endIndex

An integer specifying the element after the last element in array to add to the new array. If negative, endIndex counts backward from the end of array (-1 is the last element, -2 is the second-to-last element, etc.). If omitted, endIndex defaults to array.length.

Returns

A new array containing the elements of array from startIndex to endIndex-1.

Description

The slice( ) method creates a new array by extracting a series of elements from an existing array. The new array is a subset of the elements of the original array, starting with array[startIndex] and ending with array[endIndex-1].

Example

myList = new Array("a", "b", "c", "d", "e");

// Set myOtherList to ["b", "c", "d"]
myOtherList = myList.slice(1, 4);

// Set anotherList to ["d", "e"]
anotherList = myList.slice(3);

// Set yetAnotherList to ["c", "d"]
yetAnotherList = myList.slice(-3, -1);

See Also

Availability

Flash 5

Synopsis

array.sort()
array.sort(compareFunction)

Arguments

compareFunction

A function that dictates how to sort array.

Description

Availability

Flash 5

Synopsis

array.splice(startIndex)
array.splice(startIndex, deleteCount)
array.splice(startIndex, deleteCount, value1,...valuen)

Arguments

startIndex

The zero-relative element index at which to start element deletion and optional insertion of new elements. If negative, startIndex specifies an element counting back from the end of array (-1 is the last element, -2 is the second-to-last element, etc.).

deleteCount

An optional non-negative integer representing the number of elements to remove from array, including the element at startIndex. If 0, no elements are deleted. If omitted, all elements from startIndex to the end of the array are removed.

value1,...valuen

An optional list of one or more values to be added to array at index startIndex after the specified elements have been deleted.

Returns

A new array containing the deleted elements (the original array is modified separately to reflect the requested changes).

Description

The splice( ) method removes the elements from array[startIndex] to array[startIndex + deleteCount-1] and then optionally inserts new elements starting at startIndex. The splice( ) method does not leaves gaps in array ; it moves elements up or down to ensure the contiguity of elements in the array.

Example

myList = new Array (1, 2, 3, 4, 5);
// Deletes the second and third elements from the list
// and insert the elements "x", "y", and "z" in their place.
// This changes myList to [1, "x", "y", "z", 4, 5].
myList.splice(1, 2, "x", "y", "z");

See Also

Availability

Flash 5

Synopsis

array.unshift(value1, value2,...valuen)

Arguments

value1,...valuen

A list of one or more element values to be added to the beginning of array.

Returns

The new length of array.

Description

The unshift( ) method adds a series of elements to the beginning of an array. Elements are added in the order specified. To add elements at the end of an array, use push( ) .

Example

myList = new Array (5, 6);
myList.unshift(4);         // myList becomes [4, 5, 6]
myList.unshift(7, 1);      // myList becomes [7, 1, 4, 5, 6]

See Also

Availability

Flash 5

Synopsis

Boolean(value)

Arguments

value

An expression containing the value to be converted to a Boolean.

Returns

The result of converting value to a primitive Boolean (either true or false).

Description

Availability

Flash 5

Constructor

new Boolean(value)

Arguments

value

An expression to be resolved and, if necessary, converted to a Boolean value, then wrapped in a Boolean object.

Methods

toString( )

Convert the value of a Boolean object to a string.

valueOf( )

Retrieve the primitive value of a Boolean object.

Description

For the most part, Boolean objects are used internally. They are created automatically by the interpreter whenever a method is invoked on a primitive Boolean value and are deleted automatically after each use. We can create Boolean objects ourselves using the Boolean constructor, but there is seldom reason to do so.

Usage

Note that in practice it is much more common to use the Boolean( ) global function as a datatype-conversion tool than it is to use the Boolean class.

See Also

Availability

Flash 4; deprecated in Flash 5

Synopsis

call(frameLabel)
call(frameNumber)

Arguments

frameLabel

A string representing the label of the frame whose script should be executed.

frameNumber

The number of the frame whose script should be executed.

Description

The call( ) function executes the script attached to the frame at frameLabel or frameNumber. For example, the following code runs the script on frame 20 of the current timeline:

call(20);

In Flash 4, call( ) was used to create a crude kind of reusable subroutine (one that could not accept parameters or return any value). In Flash 5, the function statement is preferred.

Note that in Flash 5, when a script is executed remotely via call( ), any variables declared with the var keyword are considered local to that execution and expire after the script completes. To create nonlocal variables in a remotely-executed script, omit the var keyword:

var x = 10;  // Local variable; dies after script completes
x = 10;      // Timeline variable; persists after script completes

To invoke call( ) on frames outside the current timeline, use the tellTarget( ) function. The following example executes the script on frame 10 of the box clip:

tellTarget ("box") {
  call(10);
}

See Also

Availability

Constructor

new Color(target)

Arguments

target

A string or reference indicating the path to the movie clip or document level whose color will be controlled by the new object (references are converted to paths when used in a string context).

Methods

getRGB( )

Retrieve the current offset values for Red, Green, and Blue.

getTransform( )

Retrieve the current offset and percentage values for Red, Green, Blue, and Alpha.

setRGB( )

Assign new offset values for Red, Green, and Blue, while reducing percentage values to 0.

Description

var ballColor = new Color("ball");
ballColor.setRGB(0xFF0000);  // Pass setRGB( ) the hex value for red

For example, pure red would be described by the following values:

Red: 255, Green: 0, Blue: 0, Alpha: 255

whereas a partially transparent red might have the values:

Red: 255, Green: 0, Blue: 0, Alpha: 130

For the purposes of this discussion, we adopt the so-called RGB triplet notation (Red, Green, Blue) when talking about color values. Although ActionScript doesn't support decimal RGB triplets such as (255, 0, 255), it does support the hexadecimal equivalent form 0xRRGGBB, where RR, GG, and BB are two-digit hex numbers representing Red, Green and Blue. We'll also adopt the RGBA quadlet notation (Red, Green, Blue, Alpha) for convenience only in the following discussion.

We have two means of setting transformations for each color component:

• We may set the percentage of the component's original value to a number between -100 and 100. For example, we may say "set all red used in this clip to 80% of its original value."

• We may specify an amount to offset the component's original value. The offset is a number between -255 and 255. For example, we may say, "add 20 to all blue values in this clip," or, using a negative number we may say, "subtract 30 from all blue values in this clip."

R = originalRedValue   * (redTransformPercentage/100)   + redTransformOffset
G = originalGreenValue * (greenTransformPercentage/100) + greenTransformOffset
B = originalBlueValue  * (blueTransformPercentage/100)  + blueTransformOffset
A = originalAlphaValue * (alphaTransformPercentage/100) + alphaTransformOffset

If no transformations have been performed through ActionScript, the initial transformation percentage for each component defaults to 100, while the initial offset defaults to 0.

Let's look at how color transformations work with a practical example. Suppose that a clip contains an opaque red triangle (R:255, G:0, B:0, A:255) and an opaque green circle (R:0, G:255, B:0, A:255). Now further suppose that we apply a universal transformation to the clip, setting the percentage of Green to 50, the percentage of Alpha to 80, and the offset of Blue to 100 but leaving the other offsets and percentages at their defaults (0 or 100). Here's how the universal transformation affects our red triangle:

R == 255 * (100/100) +   0 == 255            // No change to Red
G ==   0 *  (50/100) +   0 == 0              // Green reduced to 50%
B ==   0 * (100/100) + 100 == 100            // Blue offset by 100
A == 255 *  (80/100) +   0 == 204            // Alpha reduced to 80%

The final transformed red triangle has the color value (R:255, G:0, B:100, A:204). Now here's how the transformation affects our green circle:

R ==   0 * (100/100) +   0 == 0              // No change to Red
G == 255 *  (50/100) +   0 == 127.5          // Green reduced to 50%
B ==   0 * (100/100) + 100 == 100            // Blue offset by 100
A == 255 *  (80/100) +   0 == 204            // Alpha reduced to 80%

The final transformed green circle has the color value (R:0, G:127.5, B:100, A:204).

To actually apply our hypothetical color transformations to a real clip, we use a Color object as we saw earlier. To set a clip's universal color offset and percentage values we use the setRGB( ) or the setTransform( ) methods (see the entries for those methods for example code). Conversely, to examine the current color transformations of a clip, we use the getRGB( ) and getTransform( ) methods. The Color class methods can produce animated color effects such as fade-ins, fade-outs, and tinting. Furthermore, because we can apply tints to each clip instance individually, the Color class provides a very efficient way to create diverse graphics with minimal assets. For example, we could create a scene full of balloons from a single movie clip that was colorized and tinted in myriad ways, as shown under the Example heading that follows.

Usage

Some points of interest for Color objects:

• Changing the color of a movie clip with a Color object will break a tween and place the movie clip under ActionScript's control, meaning that some authoring-time behaviors applied to the clip may cease functioning.

• Setting the _alpha property of a clip affects the clip's Alpha percentage as reflected by the aa property of the object returned by getTransform( ).

• Color transformations do not affect the background color of a movie or a movie clip. They apply only to solid shapes placed on the Stage.

• Manual color transformations may be applied to movie clips in the authoring tool via the Effect panel (Window Panels Effect). All such transformations are reflected in the properties of the object returned by getTransform( ). The Effect panel serves as an excellent tool for viewing and choosing color transformations while authoring a movie.

Example

// Loop to make 20 duplicates of the clip balloon
for (var i = 0; i < 20; i++) {
  // Duplicate this balloon
  balloon.duplicateMovieClip("balloon" + i, i);

  // Position this balloon on stage
  this["balloon" + i]._x = Math.floor(Math.random( ) * 550);
  this["balloon" + i]._y = Math.floor(Math.random( ) * 400);

  // Create a Color object for this balloon
  balloonColor = new Color(this["balloon" + i]);
  // Randomly assign this balloon's color using the setRGB( ) method
  balloonColor.setRGB(Math.floor(Math.random( ) * 0xFFFFFF));
}

brightness = new Color("myClip"); 
brightnessTransform = new Object( );
brightnessTransform.rb = -30; 
brightnessTransform.bb = -30;
brightnessTransform.gb = -30;
brightness.setTransform(brightnessTransform);

This last example contains code that brightens and darkens a clip according to the mouse position:

Availability

Flash 5

Synopsis

colorObj.getRGB()

Returns

A number representing the current RGB offsets of colorObj 's target.

Description

// Create a Color object
myColor = new Color("myClip");
// Set the Red offset to 255 (FF in hex)
myColor.setRGB(0xFF0000);
// Retrieve the RGB offset and convert it to hexadecimal
hexColor = myColor.getRGB( ).toString(16);
trace(hexColor);  // Displays: ff0000

Hexadecimal color values are familiar to most web developers, as they are often used in HTML tags. For example, here we use a hexadecimal number to specify the background color of a page (full values for red and blue combine to form pink):

<BODY BGCOLOR="#FF00FF">

The hex color format used in HTML tags is, in fact, the same as the format used by getRGB( ) and setRGB( ). However, it's not mandatory to use hexadecimal to interpret the return value of getRGB( ); we may also extract the individual Red, Green and Blue color offsets from the return value of getRGB( ) using the bitwise operators:

var rgb = myColorObject.getRGB( );
var red = (rgb >> 16) & 0xFF;   // Isolate the Red offset and assign it to red
var green = (rgb >> 8) & 0xFF;  // Isolate the Green offset and assign it to green
var blue  = rgb & 0xFF;         // Isolate the Blue offset and assign it to blue

With the offset values separated into individual variables, we may examine and manipulate them individually as decimal numbers. However, when we want to apply any offset value changes to a Color object, we must reassemble the offsets into a single number, as shown under the entry for the setRGB( ) method.

Usage

The getRGB( ) and setRGB( ) methods are convenient when we're directly assigning new colors to a clip without reference to the clip's original color values. However, the getTransform( ) and setTransform( ) methods are better suited to modifying the RGB components of a clip's color transformation in relation to the clip's original colors.

Color offsets are most easily read using getTransform( ), which returns each component separately rather than as a lump sum as getRGB( ) does. This is especially true when setting negative offsets with setTransform( ) due to the way that negative numbers are represented in binary.

Example

// Create a new Color object for a clip named box
boxColor = new Color("box");
// Set a new RGB offset for "box"
boxColor.setRGB(0x333366);
// Check the RGB offset for "box"
trace(boxColor.getRGB( ));      // Displays: 3355494

See Also

Color.getTransform( ), Color.setRGB( )

Availability

Flash 5

Synopsis

colorObj.getTransform()

Returns

An object whose properties contain the color transformation values for the target clip of colorObj.

Description

Table 20-4. Properties of Object Returned by getTransform( )

Usage

Availability

Flash 5

Synopsis

colorObj.setRGB(offset);

Arguments

Description

The setRGB( ) method assigns new transformation offsets for a movie clip's RGB components. The new offset is most easily specified as a six-digit hexadecimal number of the form 0xRRGGBB, where RR, GG, and BB are two-digit numbers between 00 and FF representing the Red, Green, and Blue components. For example, the RGB triplet (51, 51, 102) is equivalent to the hexadecimal value:

0x333366

Hence, to assign a gray RGB offset to a clip named menu, we could use:

var menuColor = new Color("menu");
menuColor.setRGB(0x999999);

Availability

Flash 5

Synopsis

colorObj.setTransform(transformObject)

Arguments

transformObject

An object whose properties contain the new color transformation values for the target clip of colorObj.

Description

See Also

Availability

Flash 5

Synopsis

Date()

Returns

A string containing the current date and time.

Description

Be sure not to confuse the global Date( ) function with the Date( ) class constructor. The Date( ) function returns the date formatted as a standard, if terse, string. It is convenient for humans but not very useful inside a program where you need to manipulate dates and times. For that purpose, you are better off using objects of the Date class, which allow convenient independent access to the year, month, day, and time.

Example

To place the current time and date in a text field with minimal fuss, we can use the Date( ) function as follows:

myTextField = Date( );

// Sets myTextField to a string formatted as follows:
// "Mon Aug 28 16:23:09 GMT-0400 2000"

See Also

The Date class, Date.UTC( )

Availability

Flash 5

Constructor

new Date()
new Date(milliseconds)
new Date(year, month, day, hours, minutes, seconds, ms)

Arguments

milliseconds

The number of milliseconds between the new date and midnight of January 1, 1970 UTC (Coordinated Universal Time, akin to GMT). Positive if after; negative if before. Any required local time zone adjustment is made after the date in UTC time is determined. For example, specifying a milliseconds argument of 1000 in Eastern Standard Time would create a date 1 second past midnight on January 1, 1970 in UTC time, which translates to 7:00:01 p.m. on December 31, 1969 in EST time (5 hours behind UTC time).

year

An integer specifying the year. Required when using the year,...ms constructor format. If year is one or two digits, it is treated as the number of years since 1900 (e.g., a year of 11 always refers to the year 1911, not 2011). Use four-digit numbers to specify year 2000 or later (e.g., use 2010, not 10). Three-digit years are treated as pre-1000 A.D. Note that when year is negative or less than 800, the calculation is unreliable. To specify dates prior to 1000 A.D., it's safest to use the single milliseconds constructor format.

month

An integer specifying the month, from ( January) to 11 (December), not from 1 to 12. Required when using the year,...ms constructor format. Out-of-range months are carried over to the next or previous year. For example, a month of 13 is treated as February of the following year.

day

An optional integer specifying the day, from 1 to 31. Defaults to 1 if not specified. Out-of-range days are carried over to the next or previous month. For example September 31 is treated as October 1 and September is treated as August 31.

hours

An optional integer specifying the hour, from 0 (midnight) to 23 (11 p.m.). Defaults to if not specified. AM and PM notation are not supported. Out-of-range hours are carried over to the next or previous day. For example, an hour of 25 is treated as 1 a.m. of the following day.

minutes

An optional integer specifying the minute, from to 59. Defaults to if not specified. Out-of-range minutes are carried over to the next or previous hour. For example, a minute of 60 is treated as the first minute of the following hour.

seconds

An optional integer specifying the seconds, from to 59. Defaults to if not specified. Out-of-range seconds are carried over to the next or previous minute. For example, a second of -1 is treated as the last second of the previous minute.

ms

An optional integer specifying the milliseconds, from to 999. Defaults to if not specified. Out-of-range milliseconds are carried over to the next or previous second. For example, an ms of 1005 is treated as 5 milliseconds into the following second.

Class Methods

UTC( )

Retrieve the number of milliseconds between January 1, 1970 and a supplied UTC date.

Methods

getDate( )

Retrieve the day of the month, from 1 to 31.

getDay( )

Retrieve the day of the week, as a number from 0 0 (Sunday) to 6 (Saturday).

getFullYear( )

Retrieve the four-digit year.

getHours( )

Retrieve the hour of the day from 0 to 23.

getMilliseconds( )

Retrieve the milliseconds.

getMinutes( )

Retrieve the minutes.

getMonth( )

Retrieve the month of the year, as a number from 0 (January) to 11 (December).

getSeconds( )

Retrieve the seconds.

getTime( )

Retrieve the date in internal format (i.e., the number of milliseconds between the date and January 1, 1970).

getTimezoneOffset( )

Retrieve the number of minutes between UTC and local time.

getUTCDate( )

Retrieve the day of the month in UTC time.

getUTCDay( )

Retrieve the day of the week in UTC time.

getUTCFullYear( )

Retrieve the four-digit year in UTC time.

getUTCHours( )

Retrieve the hour of the day in UTC time.

getUTCMilliseconds( )

Retrieve the milliseconds in UTC time.

getUTCMinutes( )

Retrieve the minutes in UTC time.

getUTCMonth( )

Retrieve the month of the year in UTC time.

getUTCSeconds( )

Retrieve the seconds in UTC time.

getYear( )

Retrieve the year, relative to 1900.

setDate( )

Assign the day of the month.

setFullYear( )

Assign the year in four-digit format.

setHours( )

Assign the hour of the day.

setMilliseconds( )

Assign the milliseconds.

setMinutes( )

Assign the minutes.

setMonth( )

Assign the month of the year.

setSeconds( )

Assign the seconds.

setTime( )

Assign the date in internal format (i.e., the number of milliseconds between the date and January 1, 1970).

setUTCDate( )

Assign the day of the month in UTC time.

setUTCFullYear( )

Assign the year in four-digit format in UTC time.

setUTCHours( )

Assign the hour of the day in UTC time.

setUTCMilliseconds( )

Assign the milliseconds in UTC time.

setUTCMinutes( )

Assign the minutes in UTC time.

setUTCMonth( )

Assign the month of the year in UTC time.

setUTCSeconds( )

Assign the seconds in UTC time.

setYear( )

Assign the year in four-digit, or in two-digit format for the 20th century.

toString( )

A human-readable string representing the date.

valueOf( )

The number of milliseconds between the date and midnight of January 1, 1970 UTC.

Description

We use objects of the Date class as a mechanism by which to determine the current time and date and as a means of storing arbitrary dates and times in a structured format.

Normally, however, we needn't worry about calculating the number of milliseconds to a particular date; the ActionScript interpreter takes care of that for us. When we construct a Date object, we simply describe our date as a year, month, day, hour, minute, second, and millisecond. The interpreter then converts that point in time to the internal milliseconds-from-1970 format. We may also ask the interpreter to create a new Date object using the current time. Once a Date object is created, we can use the Date class's methods to retrieve and set the date's year, month, day, hour, minute, second, and millisecond.

• We may invoke the Date( ) constructor with no arguments. This sets the new Date object to the current time.

• We may invoke the Date( ) constructor with one numeric argument: the number of milliseconds between midnight, January 1, 1970 and the date we're creating.

• We may invoke the Date( ) constructor with from two to seven numeric arguments, corresponding to the year and month (mandatory) and (optionally) the day, hour, minute, second, and millisecond of the date we're creating.

Because dates are stored internally as a single number, objects of the Date class do not have properties to retrieve and set. Rather, they have methods that we use to access the various components of a date in human-readable terms (i.e., in more convenient units). For example, to determine the month of a particular Date object, we use:

myMonth = myDate.getMonth( );

We cannot use:

myMonth = myDate.month;  // There's no such property! We have to use methods.

Usage

All dates and times are determined according to the settings on the operating system on which the Flash movie is running (not the web server) and include regional offsets. Times and dates, therefore, are only as accurate as the user's system.

Note that the Date( ) constructor may also be used as a global function to generate a string expressing the current time in the same format as would be returned by myDate.toString( ).

In Flash 5 ActionScript, it is not possible to convert a string into a Date object, as is possible in JavaScript.

Example

Dates can be added and subtracted to come up with cumulative times or elapsed times. Suppose our friend Graham decides to go traveling for a little less than a year. While he's gone, we want to keep track of how many days he's been away and how many days we have to wait for him to return. The following code takes care of our countdown:

// Assign the current time to now
var now = new Date( );

// Graham leaves September 7, 2000 (remember, months start at 0
// so September is 8, not 9)
var departs = new Date(2000,8,7);

// Graham comes back August 15, 2001
var returns = new Date(2001,7,15);

// Convert the times to milliseconds for easy comparison. 
// Then check how many milliseconds have elapsed between the two times. 
var gone = now.getTime() - departs.getTime( );

// Divide the difference between departure date and now by the number 
// of milliseconds in a day. This tells us how many days we've been waiting.
var numDaysGone = Math.floor(gone/86400000);

// Use the same technique to determine how many days we have left to wait
var left = returns.getTime() - now.getTime( );
var numDaysLeft = Math.floor(left/86400000);

// Display our days in text fields
goneOutput = numDaysGone;
leftOutput = numDaysLeft;

oneDay = 86400000;
now = new Date( );
tomorrow = new Date(now.getTime( ) + oneDay);

// We could also add one day to the date in now like this
now.setTime(now.getTime( ) + oneDay);

// Takes any Date object and returns a string of the format:
// Saturday December 16
function formatDate(theDate) {
  var months = ["January", "February", "March", "April", 
                "May", "June", "July", "August", "September", 
                "October", "November", "December"];
  var days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", 
              "Friday", "Saturday"];
  var dateString = days[theDate.getDay( )] + " "
                   + months[theDate.getMonth( )] + " "
                   + theDate.getDate( );
  return dateString;
}

now = new Date( );
trace("Today is " + formatDate(now));

The next example shows how to convert the 24-hour clock return value of getHours( ) to a 12-hour clock with AM and PM:

// Takes any Date object and returns a string of the format:
// "2:04PM"
function formatTime(theDate) {
  var hour = theDate.getHours( );
  var minute = theDate.getMinutes( ) > 9 ?
               theDate.getMinutes() : "0" + theDate.getMinutes( );
  if (hour > 12) {
    var timeString = (hour - 12) + ":" + minute + "PM";
  } else {
    var timeString = hour + ":" + minute + "AM";
  }
  return timeString;
}

now = new Date( );
trace("The time is " + formatTime(now));

Availability

Flash 5

Synopsis

date.getTimezoneOffset()

Returns

Example

When invoked in Eastern Daylight Time (EDT) during daylight savings, the following code returns the value 240 (240 minutes is 4 hours):

myDate = new Date( );
trace(myDate.getTimezoneOffset( ));  // Displays: 240

However, when invoked in EDT, during non-daylight savings times of year, the same code returns 300 (300 minutes is 5 hours), which is the real offset between Eastern Standard Time (EST) and UTC.

Availability

Flash 5

Synopsis

date.toString()

Returns

Example

trace (myDate.toString( )); // Displays a date in the format:
                           // Wed Sep 15 12:11:33 GMT-0400 1999

Availability

Synopsis

duplicateMovieClip(target, newName, depth)

Arguments

Availability

Flash 5

Synopsis

escape(string)

Arguments

string

A string (or an expression that yields a string) to be encoded.

Returns

An (almost) URL-encoded version of string.

Description

The escape( ) function effectively URL-encodes a string, except that space characters are converted to %20, not +. escape( ) is sometimes used when a Flash movie sends information to server applications or writes cookies in a browser.

To decode an encoded string, we use the global unescape( ) function.

Example

var phoneNumber = "(222) 515-1212"
escape(phoneNumber);  // yields %28222%29%20515%2D1212

See Also

Availability

Flash 4 and later

Synopsis

eval(stringExpression)

Arguments

stringExpression

A string or an expression that yields a string. Should match the name of some identifier.

Returns

The value of the variable represented by stringExpression or a reference to the object, movie clip, or function represented by stringExpression. If stringExpression does not represent a variable or a movie clip, undefined is returned.

Description

The eval( ) function provides a means of constructing a dynamic reference to an identifier based on a string of text. eval( ) converts a string to a variable, movie clip, object property, or other identifier and then evaluates that identifier. For example, here we use the return value of eval( ) to set the value of a variable:

name1 = "Kathy";
count = 1;
currentName = eval("name" + count);     // Sets currentName to "Kathy"

And here we control a dynamically-named movie clip, star1:

eval("star" + count)._x += 100;         // Move star1 right 100 pixels

But we may also use an eval( ) invocation in place of an identifier that is the lefthand operand of an assignment expression, as in:

eval("name" + count) = "Simone";        // Sets name1 to "Simone"

Note that, unlike its JavaScript cousin, eval( ) in ActionScript does not allow for the compiling and execution of arbitrary blocks of code in a string. Full support of eval( ) would require an ActionScript compiler in the Player, which would cause too great an increase in the Player size.

Usage

As of Flash 5, eval( ) is rarely needed for dynamic variable access. When managing multiple pieces of data, use arrays and objects instead.

Example

The eval( ) function is often used to convert the MovieClip._droptarget string property to a movie clip object reference. In the following example, suppose we have a series of cartoon face clips. When the user drops a food clip onto one of the faces, we retrieve the path to the face in question using _droptarget, then we use eval( ) to retrieve an object reference to that face. Finally, we send the face to a frame showing the mouth full of food:

// Convert _droptarget string to a reference
theFace = eval(food._droptarget);
// Control appropriate face clip using converted reference
theFace.gotoAndStop("full");

See Also

Availability

Synopsis

fscommand(command, arguments)

Arguments

command

A string passed to the host application, often the name of a JavaScript function.

arguments

A string passed to the host application, often an argument to the function named by command.

Description

With the fscommand( ) function, a Flash movie can communicate with the standalone Player or with the Player's host application -- the environment in which the Flash Player is running (e.g., a web browser or Macromedia Director). The fscommand( ) function is typically used in one of three ways:

• To send one of a limited set of built-in commands to the standalone Flash Player

• To send commands to a scripting language such as JavaScript or VBScript in a web browser

Table 20-5. command/argument Pairs in Standalone Player

When used in a browser, the execution of an fscommand( ) function in a movie causes the invocation of a special JavaScript function (Netscape) or VBScript function (Internet Explorer) on the page that contains the movie. The name of this special function takes the general form movieID_DoFSCommand where movieID is the name specified in the movie's OBJECT ID attribute (Internet Explorer) or EMBED NAME attribute (Netscape) from the host HTML document. When movieID_DoFSCommand( ) is invoked, the values of the fscommand( ) 's command and arguments parameters are passed to the movieID_DoFSCommand( ) function as arguments. If no movieID_DoFSCommand( ) function exists in the host page, fscommand( ) fails silently.

Note that in order for fscommand( ) to work with Netscape, the swLiveConnect attribute of the movie's EMBED tag must be set to "true". For example:

<EMBED
  NAME="testmovie"
  SRC="myMovie.swf"
  WIDTH="100%"
  HEIGHT="100%"
  swLiveConnect="true"
  PLUGINSPAGE="http://www.macromedia.com/go/flashplayer/"
</EMBED>

Usage

It is not possible to communicate with a browser via fscommand( ) under the following system configurations:

• Internet Explorer on the Macintosh OS

• Any browser running on a 68K-series Macintosh

• Any browser running on Windows 3.1

• Netscape 6

Note that fscommand( ) does not always provide the best means of communicating with a Director movie from Flash. The preferred director communication device is a getURL( ) function with either the event: or lingo: protocol. For details, see the getURL( ) function or the following Macromedia tech notes:

fscommand("quit");

To create a standalone Projector that runs fullscreen, use:

fscommand("fullscreen", "true");

To create a standalone Projector that runs fullscreen but maintains the original movie's size, use:

fscommand("fullscreen", "true");
fscommand("allowscale", "false");

Availability

Flash 4; deprecated in Flash 5

Synopsis

getProperty(movieClip, property)

Arguments

movieClip

An expression that yields a string indicating the path to a movie clip. In Flash 5, this may also be a movie clip reference because movie clip references are converted to paths when used in a string context.

property

The name of the built-in property to retrieve. Must be an identifier, not a string (e.g., _x, not "_x").

Returns

The value of movieClip's property.

Description

The getProperty( ) function retrieves the value of one of a movie clip's built-in properties. Though getProperty( ) was the only way to access object properties in Flash 4, the . and [] operators are the preferred property-access tools in Flash 5 and later.

Example

Each of the following getProperty( ) invocations retrieve the values of the _x property of a movie clip named ball on the main movie timeline:

getProperty(ball, _x);             // Relative movie clip reference
getProperty(_root.ball, _x);       // Absolute movie clip reference
getProperty("ball", _x);           // Relative path in string
getProperty("_root.ball", _x);     // Dot path in string
getProperty("/ball", _x);          // Slash path in string

The following code shows similar property access using the dot and [ ] operators:

ball._x;
_root.ball._x;
ball["_x"];
_root["ball"]["_x"];

See Also

Availability

Synopsis

getURL (URL)
getURL (URL, window)
getURL (URL, window, method)

Arguments

URL

A string specifying the absolute or relative location of the document to load or external script to run.

window

An optional string specifying the name of the browser window or frame into which to load the document. May be a custom name or one of the four presets: "_blank", "_parent", "_self", or "_top".

method

An optional string specifying the method by which to send the current timeline's variables to an external script -- either "GET" or "POST". This parameter must be a literal string, not a variable or other expression. The standalone version of the Flash Player always uses the "GET" method, regardless of the method specified.

Description

The getURL( ) function is used to:

• Load a document (usually a web page) into a web browser frame or window

• Execute a server-side script and receive the results in a browser frame or window

• Execute JavaScript code in a web browser

• Trigger events from Flash assets imported as sprites into Director

To load a document into the current window or frame, simply specify the URL of the document without supplying a window or method argument. Naturally, Flash supports absolute URLs (those that contain a protocol such as "http:" plus a server name or hardware device) and relative URLs (those that are relative to the current location):

getURL("http://www.moock.org/");                  // Absolute URL to web page
getURL("file:///C|/WINDOWS/Desktop/index.html");  // Absolute URL to local file
getURL("/whatever/index.html");                   // Relative URL, http protocol
                                                  //is assumed

To load a document into a named window or frame, supply the window or frame name as the window argument. For example:

getURL("http://www.moock.org/", "contentFrame");  // Load into named frame
getURL("http://www.moock.org/", "remoteWin");     // Load into named window

To replace the frameset that contains the current movie, use "_ parent" as the value of the window argument. For example:

getURL("http://www.moock.org/", "_parent");

To replace all framesets in a web page with a loaded document, use "_top" as the value of the window argument. For example:

getURL("http://www.moock.org/", "_top");

To open a loaded document in a new, anonymous browser window, use "_blank" as the value of the window argument. For example:

getURL("http://www.moock.org/", "_blank");

Table 20-6. Supported Protocols for getURL

on myEvent msg
  put "The message received from Flash was " && msg
end

You can also trigger Lingo to be executed from a Flash sprite within Director using the "lingo:" keyword, such as:

getURL ("lingo: beep");  // Tell Director to play a beep sound

Note that Director 8.0 cannot import Flash 5 .swf files, but an updated Flash asset Xtra is expected to be available by the time you read this.

Finally, getURL( ) can also be used to execute JavaScript code. Here we invoke a simple JavaScript alert using getURL( ):

getURL ("javascript: alert('hello world');");

Note that execution of JavaScript code from a URL does not work in Internet Explorer 4.5 for Macintosh.

Example

Here's the code for a standard button that links to a web page:

on (release) {
  getURL("http://www.macromedia.com/");
}

Bugs

Internet Explorer 4.5 (IE 4.5) and older versions on Macintosh do not support the "POST" method of a getURL( ) call. To service those browsers, use "GET" instead of "POST" (subject to the length limitations cited earlier).

In most browsers, getURL( ) relative links are resolved relative to the HTML file that contains the .swf file. In IE 4.5 and older versions on Macintosh, relative links are resolved relative to the location of the .swf file, not the HTML file, which causes problems when the two are in different directories. To avoid the problem, either place the .swf and the .html file in the same directory or use absolute URLs when invoking getURL( ), such as:

getURL ("http://www.someserver.com/")

See Also

Availability

Flash 5

Synopsis

getVersion()

Returns

A string containing version and platform information for the Flash Player hosting the current movie.

Description

The getVersion( ) function tells us the platform and Flash Player version being used to view a movie. It can be used to conditionally execute different code for specific versions of the Flash Player or on certain operating systems. The string returned by getVersion( ) takes the form:

platform majorVersion,minorVersion,buildNumber,patch

Where platform is a code indicating the platform ("WIN", "MAC", or "UNIX"), followed by the major version number, the minor version number, and the build (a.k.a. revision) number. The last item, patch, is typically 0. For example:

WIN 5,0,30,0   // Version 5.0, Build 30 (5.0r30) on Windows 
MAC 5,0,41,0   // Version 5.0, Build 41 (5.0r41) on Macintosh
UNIX 4,0,12,0  // Version 4.0, Build 12 (4.0r12) on Unix

Despite the Macromedia documentation's claim to the contrary, getVersion( ) does work in the Flash authoring tool's Test Movie mode. It reports the version number of the Player embedded in the authoring tool (which is not the same as the version of the authoring tool itself). For example, the Flash 5 authoring tool embeds the 5.0 r30 version of the Player, so its getVersion( ) function reports:

WIN 5,0,30,0
or
MAC 5,0,30,0

Any time a major or minor version of the authoring tool is created, the buildNumber restarts at 0. However, in the typical development cycle of the Flash authoring tool, many builds of the Flash Player are produced before the final version of the authoring tool is released. The build number of the first new major version of a Player is, hence, usually greater than 0. For example, the Flash 5 Player was first officially released at Build 30. Presumably, when Flash 6 is introduced, the Flash 6 Player will return something like:

WIN 6,0,xx,0

but if a movie created in Flash 6 is played back in the Flash 5 Player, getVersion( ) would still return:

WIN 5,0,30,0

Availability

Flash 2 and later

Synopsis

gotoAndPlay(frameNumber)
gotoAndPlay(frameLabel)
gotoAndPlay(scene, frameNumber)
gotoAndPlay(scene, frameLabel)

Arguments

frameLabel

A string indicating the label of the frame to which the playhead of the current timeline should proceed before playing. If frameLabel is not found, the playhead is sent to the first frame of the timeline.

scene

An optional string indicating the name of the scene that contains the specified frameNumber or frameLabel. If not supplied, the current scene is assumed.

Description

When invoked without a scene argument, gotoAndPlay( ) sends the playhead of the current timeline to the frame specified by either the frameNumber or frameLabel and then plays the timeline from that point. The "current timeline" is the movie clip or movie from which the gotoAndPlay( ) function is invoked.

If two arguments are specified in the gotoAndPlay( ) function call, the first argument is assumed to be the scene. If only one argument is specified, it is treated as a frameNumber or frameLabel, and the current scene is assumed.

When invoked with a scene argument, gotoAndPlay( ) moves the playhead to the frame number or label in the specified scene and then plays that scene. If a scene argument is used, the gotoAndPlay( ) function must be invoked from the _root timeline; otherwise, the operation fails silently and the playhead is not sent to the destination frame. Note that scenes are flattened into a single timeline during movie playback. That is, if scene 1's timeline contains 20 frames, and scene 2's timeline contains 10 frames, then we can send the playhead to frame 5 of scene 2 using gotoAndPlay(25);.

TIP

I recommend against using scenes when working with ActionScript-intensive movies. Unlike movie clips, scenes are not represented by objects and cannot be manipulated directly by most built-in functions. It's normally better to use labels and movie clips as pseudo-scenes in your timeline instead of Flash's scene feature.

The global gotoAndPlay( ) function affects only the current timeline. The frames or state of other movie clips within the current timeline are not affected. To cause other movie clips to play, you must issue a separate play( ) or gotoAndPlay( ) command for each movie clip. To apply the gotoAndPlay( ) function to a clip other than the current movie clip, use the movie clip method form, myClip.gotoAndPlay( ).

Bugs

Example

// Go to frame 5 of the current timeline and play it
gotoAndPlay(5);
// Go to frame 10 of the exitSequence scene, and play it
gotoAndPlay("exitSequence", 10);
// Go to frame "goodbye" of the exitSequence scene, and play it
gotoAndPlay("exitSequence", "goodbye");
// Caution! This plays the frame labeled "exitSequence" in the current scene.
gotoAndPlay("exitSequence");
// This plays frame 1 of the exitSequence scene
gotoAndPlay("exitSequence", 1);

See Also

gotoAndStop( ), MovieClip.gotoAndPlay( ), play( ), stop( )

Availability

Flash 2 and later

Synopsis

gotoAndStop(frameNumber)
gotoAndStop(frameLabel)
gotoAndStop(scene, frameNumber)
gotoAndStop(scene, frameLabel)

Arguments

frameNumber

A positive integer indicating the number of the frame to which the playhead of the current timeline should proceed. If frameNumber is less than 1 or greater than the number of frames in the timeline, the playhead is sent to either the first or last frame, respectively.

frameLabel

A string indicating the label of the frame to which the playhead of the current timeline should proceed. If frameLabel is not found, the playhead is sent to the first frame of the timeline.

scene

An optional string indicating the name of the scene that contains the specified frameNumber or frameLabel. If not supplied, the current scene is assumed.

Description

When invoked without a scene argument, gotoAndStop( ) sends the playhead of the current timeline to the frame specified by either the frameNumber or frameLabel argument. The "current timeline" is the movie or movie clip from which the gotoAndStop( ) function is invoked. The playhead will stop at the target frame; it will not advance automatically after arriving at the target frame.

If two arguments are specified in the gotoAndStop( ) function call, the first argument is assumed to be the scene. If only one argument is specified, it is treated as a frameNumber or frameLabel, and the current scene is assumed.

When invoked with a scene argument, gotoAndStop( ) moves the playhead to the frame number or label in the specified scene and then halts playback. If a scene argument is used, the gotoAndStop( ) function must be invoked from the _root timeline; otherwise, the operation fails silently and the playhead is not sent to the destination frame.

The global gotoAndStop( ) function affects only the current timeline. The frames or state of other movie clips within the current timeline are not affected. To move the playhead of other movie clips, you must issue a separate gotoAndStop( ) command for each movie clip. To apply the gotoAndStop( ) function to a clip besides the current movie clip, use the movie clip method of the form myClip.gotoAndStop( ).

Bugs

Example

// Go to frame 5 of the current timeline and stop there
gotoAndStop(5);
// Go to frame 20 of the introSequence scene and stop there
gotoAndStop("introSequence", 20);
// Go to frame "hello" of the introSequence scene, and stop there
gotoAndStop("introSequence", "hello")
// Caution! This goes to the frame labeled "introSequence" in the current scene
gotoAndStop("introSequence")
// This goes to frame 1 of the introSequence scene
gotoAndStop("introSequence", 1)

See Also

Availability

Flash 5

Synopsis

#include path

Arguments

path

A string indicating the name and location of the script file to import, which may be specified relative to the .fla file or as an absolute path (see samples under Example). Note that forward slashes, not backslashes should be used in the path. Script files should be named with the .as file extension.

Description

The #include directive brings script text from an external text file (preferably one with the .as extension) into the current script, placing it directly where the #include command occurs in the script. The #include operation is performed at compile time, meaning that the text included in a movie is the text that existed at the time the movie was tested, exported, or published from the authoring tool. If the external file changes after the movie is exported, the changes will not be reflected in the movie. In order for the changes to be added to the movie, the movie must be re-exported.

The #include directive is used to incorporate the same block of code in multiple scripts or across Flash projects (much as you'd use an external asset library). You would do this in order to centralize your code, when maintaining code in a version-control system tool (such as CVS or Microsoft Visual Source Safe), or when using an external text editor that you prefer over the ActionScript editor. It is also handy when a programmer is working separately from, say, a graphic artist creating the Flash animations. External files lend themselves well to code repositories, such as a library of functions that are independent of the current timeline or movie clip. They tend to be less useful for code that needs to be tightly integrated with the Flash file.

Usage

Note that an #include directive begins with a pound sign (#), does not use parentheses, and must not end in a semicolon. Any #include statements that end in a semicolon will cause an error and will not successfully import an external script. If the file can't be found at the specified path, the directive will cause an error and no external text will be included. The text in the external file is also checked when performing a syntax check using the Check Syntax command (Ctrl-T or Command-T) in the Actions panel menu (found under the arrow button in the upper-right corner of the panel).

Example

The following code imports an external .as file named myScript.as into the current .fla file. When using a relative path, myScript.as would have to be in the same folder as the .fla file containing the include directive:

#include "myScript.as"

We can construct a relative path including a subdirectory. The following assumes that myScript.as is one level down from the current .fla file in a subdirectory named includes:

#include "includes/myScript.as"

Use two dots to indicate the folder above the current folder. The following assumes that myScript.as is one level up from the current .fla file:

#include "../myScript.as"

The following assumes that myScript.as is in a subdirectory named includes adjacent to the subdirectory containing the current .fla file:

#include "../includes/myScript.as"

You can also specify an absolute path to any folder, such as:

#include "C:/WINDOWS/Desktop/myScript.as"

but absolute paths are not cross-platform and may need to be changed if you compile the .fla file on a different machine with different directories. Note the differences in the drive letter specification:

#include "C:/WINDOWS/Desktop/myScript.as"                // Windows
#include "Mac HD:Desktop folder:working:myScript.as"     // Macintosh

See Also

Availability

Flash 5

Synopsis

Infinity

Access

Read-only

Description

Any number in ActionScript that exceeds the maximum allowed numeric range is represented by the numeric constant Infinity. The largest value allowed in ActionScript is represented by Number.MAX_VALUE (1.7976931348623157e+308).

Example

The result of a calculation that exceeds the largest allowed number is Infinity. For example:

Number.MAX_VALUE * 2;    // Yields Infinity

Infinity also results when dividing a positive number by zero:

1000 / 0;                // Yields Infinity

Usage

Infinity is shorthand for Number.POSITIVE_INFINITY.

See Also

Availability

Flash 5

Synopsis

-Infinity

Access

Read-only

Description

Any number in ActionScript that exceeds the allowed negative numeric range is represented by the numeric constant -Infinity. The smallest negative value (the one with the largest absolute value) allowed in ActionScript is -Number.MAX_VALUE, which is equivalent to -1.7976931348623157e+308.

Example

The result of a calculation that is smaller than (i.e., more negative than) the smallest allowed negative number is -Infinity. For example:

-Number.MAX_VALUE * 2;    // Yields -Infinity

-Infinity also results when dividing a negative number by zero:

-1000 / 0;                // yields -Infinity

Usage

-Infinity is shorthand for Number.NEGATIVE_INFINITY.

See Also

Availability

Flash 5

Synopsis

isFinite(number)

Arguments

number

Any numeric value or expression that yields a numeric value.

Returns

A Boolean value; true if the number falls between Number.MAX_VALUE and -Number.MAX_VALUE (inclusive), false if not. If number does not belong to the number datatype, number is converted to the number type before isFinite( ) executes.

Description

The isFinite( ) function simply checks if a number is in the legal numeric value range of ActionScript. Use isFinite( ) before executing code that requires a legitimate number to operate properly.

Example

if (!isFinite(x * y)) {           // Test if the number is not finite
  trace ("The answer is too large to display. Try again.");
}
isFinite(-2342434);              // Yields true
isFinite(Math.PI);               // Yields true
isFinite(Number.MAX_VALUE * 2)   // Yields false

See Also

Availability

Flash 5

Synopsis

isNaN(value)

Arguments

value

The expression to test.

Returns

A Boolean value: true if value is the special numeric value NaN; otherwise, false.

Description

To test whether or not a value is equal to the special numeric value NaN, we must use the isNaN( ) function because NaN does not test equal to itself in an ordinary equality test. For example, the expression:

NaN == NaN;

yields the value false. The isNaN( ) function is often used to check whether a mathematical error (such as zero divided by itself) has occurred in a phrase of code or whether converting a value to a legitimate number has failed. Because isNaN( ) returns true when the expression is not a valid numeric expression, you'll often use the logical NOT operator (!) along with isNaN( ) (something that is not not a number is a number). Note that 0/0 yields NaN, but all positive numbers divided by yield Infinity, and all negative numbers divided by yield -Infinity.

Example

// Set a value
var x = "test123";
// Check if x is a legitimate number before using it is in a math expression.
// This is a handy technique for user input in text fields, which always a string.
if (!isNaN(parseFloat(x))) {
  var y = parseFloat(x) * 2;
}

See Also

Availability

Flash 5

Synopsis

Key.property

Key.methodName()

Properties

Table 20-7. Key Object Keycode Properties

Methods

getAscii( )

Returns the ASCII value of the last key pressed

getCode( )

Returns the keycode of the last key pressed

isDown( )

Checks if a specific key is currently depressed

isToggled( )

Checks if the Num Lock, Caps Lock, or Scroll Lock keys are activated

Description

The Key object is used to determine which keys are currently depressed and which key was last depressed. We can use it to build interfaces controlled by the keyboard, such as a game with a spaceship moved via the arrow keys.

Because not all keyboards are identical, keyboard-controlled interfaces can sometimes be tricky to create. By choosing our scripting tools correctly, however, we can ensure that all users have the same experience.

• We may check if a key is currently depressed via the isDown( ) method. This is recommended for cases in which keyboard input is constantly required, such as in video games.

• We may check which key was last depressed using the getCode( ) and getAscii( ) methods. This is recommended for typical keyboard-driven interfaces in which specific operations are performed when keys are pressed. You would ordinarily use these methods within a keyDown event handler in order to distinguish between different keys. There is no need to constantly check (i.e., poll) for the last key pressed. In fact, doing so would lead to erroneously repeating some operation even if a key wasn't pressed repeatedly. That is, you should generally check getCode( ) and getAscii( ) within a keyDown event handler only because the handler is guaranteed to be called once and only once for each keystroke.

if (Key.isDown(Key.UP)) {
  trace("The up arrow is being pressed");
}

When working with a keycode that is not a letter or a number and is not available as a property of Key -- such as those of the function keys (F1, F2, etc.) -- it's safest to create a quick test movie to check the keycode of the desired key, as follows:

trace(Key.getCode( ));

Availability

Flash 5

Synopsis

Key.getAscii()

Returns

An integer representing the ASCII value of the last key pressed.

Description

The getAscii( ) method returns the ASCII value of the last key that was pressed. Since not all keys have an ASCII value, getAscii( ) is normally used for detecting letters and numbers from the Latin 1 character set (Western European languages). Unlike getCode( ), getAscii( ) distinguishes between upper- and lowercase letters. But unlike getCode( ), it cannot differentiate between two keys with the same ASCII value, such as the 8 key on the main keyboard and the 8 key on the numeric keypad.

To detect the pressing of specific keys relative to their physical location on a keyboard rather than their ASCII value (such as would be desirable when using four keys in a diamond pattern to control game play), use getCode( ).

Example

The following example demonstrates keystroke detection for a simple hangman word game. It uses a keyDown event handler to identify the pressing of a key and adds that key to a list of user guesses:

onClipEvent (keyDown) {
  var lastKey = Key.getAscii( );
  guessNum++;
  userGuesses[guessNum] = String.fromCharCode(lastKey);
}

See Also

Availability

Flash 5

Synopsis

Key.getCode()

Returns

An integer representing the keycode of the last key pressed.

Description

The getCode( ) method returns the keycode of the last key that was pressed, which is an arbitrary number representing the physical location of a key on the keyboard. On non-Windows operating systems, the native keycode system is translated automatically by Flash to the Windows equivalent, so getCode( ) provides a cross-platform means of referring to specific keys. The getCode( ) method can also be used to differentiate between two keys with the same ASCII value. For example, it can differentiate between the 8 key on the main keyboard and the 8 key on the numeric keypad, whereas getAscii( ) cannot. However, getCode( ) cannot differentiate between upper- and lowercase letters (for example, A and a use the same keycode because they are produced using the same key).

Availability

Flash 5

Synopsis

Key.isDown(keycode)

Arguments

keycode

A number representing the keycode of the key to check. May also be one of the Key constants (e.g., Key.UP, Key.BACKSPACE).

Returns

A Boolean indicating whether the key specified by keycode is pressed (true) or not pressed (false).

Description

The isDown( ) method tells us whether the key specified by keycode is currently being pressed. It offers arbitrary, immediate access to the state of the keyboard and is best used with systems that require constant key-based input or that detect the pressing of simultaneous keys.

One important advantage of isDown( ) over getCode( ) and getAscii( ) is its ability to detect the simultaneous pressing of multiple keys. By checking for both Key.UP and Key.RIGHT, for example, we may determine that a spaceship in a game should be moved diagonally. Depending on the placement of the specific keys being tested, the maximum number of keys that can be simultaneously detected may be as low as three.

Example

The isDown( ) method is normally used to create systems that undergo a constant update with each passing frame. In the following code, we rotate and thrust a spaceship on any frame where the appropriate arrow keys are being pressed. Note that if you need to detect two keys simultaneously, you should use separate if statements. In this example, the state of the right arrow key is ignored if the left arrow key is also being depressed. But regardless, the state of the up arrow key is always checked in a separate if statement. A working version of this spaceship example is available from the online Code Depot:

// Code on a spaceship clip
onClipEvent (enterFrame) {
  if (Key.isDown(Key.LEFT)) {          // Left arrow
    _rotation -= 10;
  } else if (Key.isDown(Key.RIGHT)) {  // Right arrow
    _rotation += 10;
  }
  if (Key.isDown(Key.UP)) {            // Up arrow
    thrust += 10;
  }
}

See Also

Availability

Flash 5

Synopsis

Key.isToggled(keycode)

Arguments

keycode

An integer keycode, usually the keycode of the Caps Lock key (20), Num Lock key (144), or Scroll Lock key (145). May also be the key constant Key.CapsLock.

Returns

A Boolean indicating whether the key specified by keycode is on (true) or off (false).

Description

Availability

Flash 3 and later

Synopsis

_level0
_level1
_level2
...
_leveln

Access

Read-only

Description

Multiple .swf files may be loaded into the Flash Player for simultaneous display. Each loaded .swf resides on its own level in the document level stack. (A .swf file on a higher level number will obscure lower levels if they occupy the same portion of the Stage.) The _leveln property stores a reference to the main timeline of a .swf loaded into a document level in the Player. Each document level is represented by a numbered property, such as _level0, _level1, _level2, and so on.

The original document loaded into any Flash Player is considered _level0.

Example

A _leveln reference is normally used to control movies on other levels of the document stack. For example, here we play the movie on level 2:

_level2.play( );

We can also use _leveln in combination with movie clip references to control clips contained by a movie on any level in the document stack. For example:

_level1.orderForm.titleBar.play( );

A _leveln reference may also be used as the value of the target argument of several functions, including loadMovie( ), unloadMovie( ), loadVariables( ) and print( ). If the level does not yet exist, you should specify the level reference within quotes. If used without quotes, a nonexistent level is considered undefined and may cause the command to operate on the current timeline instead of the new, undefined level. For example, when executed from the main timeline of _level0, the following will replace the movie in _level0 if _level1 has not yet been defined:

loadMovie("myMovie.swf", _level1);

The following is a safer approach if you can't guarantee that the level already exists:

loadMovie("myMovie.swf", "_level1");  // Works even if _level1 doesn't exist

Of course, from other levels, you may wish to refer to the original level, using _level0, such as:

startDrag(_level0, true);

See Also

Availability

Flash 4 and later. The loadMovie( ) function in Flash 5 corresponds to the Flash 4 Load Movie with a target path.

Synopsis

loadMovie(URL, target)
loadMovie(URL, target, method)

Arguments

URL

A string specifying the absolute or relative file path to the external .swf file to load. All URLs must use forward slashes, and absolute URLs must include either the http:// or file|/// protocol reference.

target

A string indicating the movie clip or document level that will host the external .swf file. May also be a reference to an existing movie clip or document level (references are converted to paths when used in a string context).

method

An optional string indicating the method by which to send variables to an external script. The legal values for method are "GET" and "POST". This parameter must be a literal, not a variable or other expression. The standalone version of the Flash Player always uses the "GET" method regardless of the method specified.

Description

The loadMovie( ) function imports the .swf file located at URL into the Flash Player.

If target is a reference to an existing movie clip or a string indicating the path to a movie clip, the loaded .swf file is placed into the specified clip (causing the eviction of any previous content). To load a movie into the current movie clip, use the empty string as the target parameter, as in:

loadMovie("myMovie.swf", "")

If target is a reference to an existing document level (such as _level2) or a string indicating the path to a document level (such as "_level2"), then the .swf is placed into the specified document level. Loading a movie into _level0 clears the Player of all content and places the new .swf file into _level0.

It is possible to send variables along with a loadMovie( ) invocation, in which case URL is normally the location of a script that returns a .swf file based on the variables sent. To send variables with a loadMovie( ) call, we include the method argument (set to either "GET" or "POST"). "GET" sends the current movie clip timeline variables as a query string attached to the script URL. "POST" sends the current movie clip timeline variables after the HTTP POST-request header. The "POST" method is not available in the standalone Flash Player. Because most web servers restrict the length of URLs to between 255 and 1024 characters, use "POST" instead of "GET" to transfer larger amounts of data.

Over a web server, loadMovie( ) invocations that use the "GET" method can pass variables to a loaded movie without the help of an intervening script. Here, we load the external movie myMovie.swf into level 1 of the Player document stack, passing it the variables from the current timeline:

loadMovie("myMovie.swf", "_level1", "GET");

Variables passed to the loaded movie are defined on that movie's main timeline. This technique works only when the loadMovie( ) request is handled by a web server. Attempts to use the "GET" method with loadMovie( ) using local files will cause an "Error opening URL" error.

Usage

Be careful when using movie clip and level references as the target argument of loadMovie( ). If a loadMovie( ) 's target argument yields undefined, the loadMovie( ) function uses the current timeline as its target. Similarly, target references that yield the empty string cause loadMovie( ) to operate on the current timeline. In particular, this causes problems for loading movies onto new, unoccupied levels. Consider the following code:

loadMovie("myMovie.swf", _level1);

If no _level1 object exists prior to the execution of that statement, that code will load myMovie.swf into the timeline that contains the loadMovie( ) statement, not _level1! To avoid the problem, you can use loadMovieNum( ) instead. Alternatively, you can use a string for the target parameter to loadMovie( ), as in:

loadMovie("myMovie.swf", "_level1");

Availability

Flash 4 and later

Synopsis

loadVariables(URL, target)
loadVariables(URL, target, method)

Arguments

URL

A string specifying the path to a variable source -- either a server-side script that returns variables or a text file containing variables.

target

A string indicating the path to the movie clip or document level on which the loaded variables will be defined. May also be a reference to a movie clip or document level (references are converted to paths when used in a string context).

method

An optional string indicating the method by which to send variables to an external script. If specified, the variables from the current timeline are sent to the script and target receives the loaded variables. If omitted, variables are retrieved but none are sent. The legal values for method are "GET" and "POST". This parameter must be a literal, not a variable or other expression. The standalone version of the Flash Player always uses the "GET" method regardless of the method specified.

Description

Normally, we define variables inside our movies using ActionScript. However, using loadVariables( ), we may also import variables into a movie from a text file or a server-side application such as a Perl script. Variables loaded via loadVariables( ) are scoped to the movie clip or level specified by target and are always of the string datatype. To attach loaded variables to the current timeline, use the empty string as the value of the target argument. For example:

loadVariables("myVars.txt", "");  // Loads the variables from myVars.txt onto
                                  // the current timeline

Whether the variables to be loaded reside in a text file or are composed by a script, they must be formatted according to the rules of URL encoding, as follows:

• Every variable name should be separated from its value with an equals sign, without spaces, as in firstName=stephen.

• Multiple variable name/value pairs should be separated by ampersands (&), as in firstName=stephen&lastName=burke.

• Spaces should be replaced with plus (+) signs.

• Any character that is not a space, a number (1-9), or an unaccented Latin 1 letter (a-z, A-Z) should be replaced by a hexadecimal escape sequence of the form %xx, where xx is the hex Latin 1 code point of the character.

For example, the following code shows the contents of a text file to be imported into Flash via loadVariables( ). The imported variables are name and address, which have the values "stephen" and "65 nowhere st!", respectively:

name=stephen&address=65+nowhere+st%21

A text file for use with loadVariables( ) is simply a regular text file containing URL-encoded variables, as shown previously. To load variables from an external text file, we specify the path of the file as the URL argument in our loadVariables( ) function invocation. For example:

// Load the variables from myVariables.txt into the main movie timeline
loadVariables("myVariables.txt", "_root");

loadVariables( ) may also be used with a script or server application that outputs URL-encoded variables. When a script sends data to a Flash movie in response to a loadVariables( ) function, the script should set the MIME type of the data as: "application/x-www-urlform-encoded". Here's a typical MIME-setting statement from a Perl script:

print "Content-type: application/x-www-urlform-encoded\n\n";

Table 20-8. Domain-Based loadVariables( ) Security Restrictions

Domain restriction is an intentional security feature of Flash, but it can be circumvented with either a proxy script running on siteX that acts as a go-between for Flash and siteY, or a DNS alias on siteX that points to siteY. For more information, see:

Availability

Flash 5

Synopsis

Math.propertyName
Math.methodName()

Properties

LN10

The natural logarithm of 10 (log_e10), approximately 2.30259.

LN2

The natural logarithm of 2 (log_e2), approximately 0.69315.

LOG10E

The base-10 logarithm of e, approximately 0.43429.

LOG2E

The base-2 logarithm of e, approximately 1.44270. See bug noted in detailed listing.

PI

The ratio of a circle's circumference to its diameter, approximately 3.14159.

SQRT1_2

The reciprocal of the square root of 2, approximately 0.70711.

SQRT2

Square root of 2, approximately 1.41421.

Methods

abs( )

Compute the absolute value of a number.

acos( )

Compute the arc cosine of a number.

asin( )

Compute the arc sine of a number.

atan( )

Compute the arc tangent of a number.

atan2( )

Compute the angle of a point, relative to the x-axis.

ceil( )

Round a number up to the next integer.

cos( )

Compute the cosine of an angle.

exp( )

Raise e to a specified power.

floor( )

Return the closest integer less than or equal to the input.

log( )

Compute the natural logarithm of a number.

max( )

Determine the larger of two numbers.

min( )

Determine the smaller of two numbers.

pow( )

Raise a number to a specified power.

random( )

Retrieve a random floating-point number between 0 and 1.

round( )

Calculate the closest integer to a number.

sin( )

Compute the sine of an angle.

sqrt( )

Compute the square root of a number.

tan( )

Compute the tangent of an angle.

Description

The Math object provides access to built-in mathematical functions (accessed through methods) and constant values (accessed through properties). These functions and constants are used to perform potentially complex calculations with relative ease.

Note that the properties and methods of the Math object may be used in movies exported to the Flash 4 format, in which case Flash will approximate the calculations. The resulting values are reasonable approximations but not necessarily identical to the native Flash 5 functions. The Flash 4 values are sufficiently accurate for "close-enough" applications such as graphics display but are not accurate enough for critical financial or engineering calculations.

Note that the trigonometric functions require angles to be measured in radians whereas Flash's MovieClip._rotation property is measured in degrees. There are 2 radians in a circle (1 radian is approximately 57.3 degrees). To convert from radians to degrees, use the formula:

degrees = (radians / Math.PI) * 180;

To convert from degrees to radians, use the formula:

radians = (degrees / 180) * Math.PI;

See Also

Availability

Flash 5; may be used when exporting Flash 4 movies

Synopsis

Math.atan2(y, x)

Arguments

y

The y-coordinate of the point.

x

The x-coordinate of the point.

Returns

The angle, in radians, of the point (x, y) from the center of a circle, measured counterclockwise from the circle's positive horizontal axis (i.e., the X-axis). Ranges from to -. (Negative values indicate angles below the X-axis).

Description

The atan2() method, like atan( ), performs an arc tangent calculation but uses x- and y-coordinates, rather than their ratio, as arguments. That is, calculating an arc tangent with atan2( ) as:

Math.atan2(9, 3);  // Yields 1.24904577239825

is equivalent to calculating the arc tangent with atan( ), using the ratio of 9/3 (or 3), as follows:

Math.atan(3);      // Same thing

Usage

Note that the y -coordinate is passed as the first argument to atan2( ), whereas the x-coordinate is passed as the second argument. This is intentional and required. It mirrors the structure of tangent, which is the ratio of the side opposite an angle (y) divided by the side adjacent to the angle (x).

Example

Availability

Flash 5; may be used when exporting Flash 4 movies

Synopsis

Math.E

Description

Availability

Flash 4 and later

Synopsis

textField.maxscroll

Returns

A positive integer representing the line number of the last legal top line of a text field.

Description

The maxscroll property tells us the largest allowed scroll value for a text field. It represents the number of the last line in a text field that may be used as the top line in its viewable region.

The maxscroll property can be used with the scroll property to manage a scrolling-text field.

See Also

Availability

Flash 5

Synopsis

Mouse.methodName

Methods

hide( )

Hides the mouse pointer.

show( )

Enables the mouse pointer.

Description