Video.width
Availability
Flash Player 6.
Usage
my_video.width:Number
Description
Property (read-only); an integer specifying the width of the video stream, in pixels. For live
streams, this value is the same as the Camera.width property of the Camera object that is
capturing the video stream. For FLV files, this value is the width of the file that was exported as an
FLV file.
You may want to use this property, for example, to ensure that the user is seeing the video at the
same size at which it was captured, regardless of the actual size of the Video object on the Stage.
Example
See the examples for Video.height.
Video.width 1003

CHAPTER 2
ActionScript Language Reference
void
Availability
Flash Player 5.
Usage
void (expression)
function functionName():Void {}
Description
Usage 1: Operator; a unary operator that discards the expression value and returns an undefined
value. The void operator is often used in comparisons using the equality (==) operator to test for
undefined values.
Usage 2: Data type; used in function definitions to indicate that a function will not return a value.
Example
Usage 1: In the following ActionScript, the void operator is used to test for undefined values:
if (someUndefinedVariable == void (0)) {
trace("someUndefinedVariable is undefined");
}
The previous code can also be written in the following way:
if (someUndefinedVariable == undefined) {
trace("someUndefinedVariable is undefined");
}
Usage 2: In the following example, a function that returns a value is defined using the Void return
type, which results in a compile-time error:
function myFunction():Void {
return "This will cause a compile-time error.";
}
/* the following function call will generate a compile-time error:
**Error** Scene=Scene 1, layer=Layer 1, frame=1:Line 2: A function with return
type Void may not return a value.
return "This will cause a compile-time error.";
*/
myFunction();
1004 Chapter 2: ActionScript Language Reference

CHAPTER 2
ActionScript Language Reference
while
Availability
Flash Player 4.
Usage
while(condition) {
statement(s);
}
Parameters
condition An expression that evaluates to true or false.
statement(s) The instructions to execute if the condition evaluates to true.
Returns
Nothing.
Description
Statement; evaluates a condition and if the condition evaluates to true, runs a statement or series
of statements before looping back to evaluate the condition again. After the condition evaluates to
false, the statement or series of statements is skipped and the loop ends.
The while statement performs the following series of steps. Each repetition of steps 1 through 4
is called an iteration of the loop. The condition is retested at the beginning of each iteration, as
shown in the following steps:
1. The expression condition is evaluated.
2. If condition evaluates to true or a value that converts to the Boolean value true, such as a
nonzero number, go to step 3.
Otherwise, the while statement is completed and execution resumes at the next statement
after the while loop.
3. Run the statement block statement(s).
4. Go to step 1.
Looping is commonly used to perform an action while a counter variable is less than a specified
value. At the end of each loop, the counter is incremented until the specified value is reached. At
that point, the condition is no longer true, and the loop ends.
The curly braces ({}) used to enclose the block of statements to be executed by the while
statement are not necessary if only one statement will execute.
Example
In the following example, the while statement is used to test an expression. When the value of i
is less than 20, the value of i is traced. When the condition is no longer true, the loop exits.
var i:Number = 0;
while (i

i += 3;
}
The following result is displayed in the Output panel.
0
3
6
9
12
15
18
See also
do while, continue, for, for..in
1006 Chapter 2: ActionScript Language Reference

CHAPTER 2
ActionScript Language Reference
with
Availability
Flash Player 5.
Usage
with (object:Object) {
statement(s);
}
Parameters
object An instance of an ActionScript object or movie clip.
statement(s) An action or group of actions enclosed in curly braces ({}).
Returns
Nothing.
Description
Statement; lets you specify an object (such as a movie clip) with the object parameter and
evaluate expressions and actions inside that object with the statement(s) parameter. This
prevents you from having to repeatedly write the object’s name or the path to the object.
The object parameter becomes the context in which the properties, variables, and functions in
the statement(s) parameter are read. For example, if object is my_array, and two of the
properties specified are length and concat, those properties are automatically read as
my_array.length and my_array.concat. In another example, if object is state.california,
any actions or statements inside the with statement are called from inside the california
instance.
To find the value of an identifier in the statement(s) parameter, ActionScript starts at the
beginning of the scope chain specified by the object and searches for the identifier at each level
of the scope chain, in a specific order.
The scope chain used by the with statement to resolve identifiers starts with the first item in the
following list and continues to the last item:
• The object specified in the object parameter in the innermost with statement.
• The object specified in the object parameter in the outermost with statement.
• The Activation object. (A temporary object that is automatically created when a function is
called that holds the local variables called in the function.)
• The movie clip that contains the currently executing script.
• The Global object (built-in objects such as Math and String).
To set a variable inside a with statement, you must have declared the variable outside the with
statement, or you must enter the full path to the Timeline on which you want the variable to live.
If you set a variable in a with statement without declaring it, the with statement will look for the
value according to the scope chain. If the variable doesn’t already exist, the new value will be set
on the Timeline from which the with statement was called.
with 1007

Instead of using with(), you can use direct paths. If you find that paths are long and
cumbersome to type, you can create a local variable and store the path in the variable, which you
can then reuse in your code, as shown in the following ActionScript:
var shortcut = this._parent._parent.name_txt;
shortcut.text = "Hank";
shortcut.autoSize = true;
For more information on best practices in writing code and code readability, see Chapter 3,
“Avoiding the with statement,” on page 87 of Using ActionScript in Flash.
Example
The following example sets the _x and _y properties of the someOther_mc instance, and then
instructs someOther_mc to go to Frame 3 and stop.
with (someOther_mc) {
_x = 50;
_y = 100;
gotoAndStop(3);
}
The following code snippet shows how to write the preceding code without using a with
statement.
someOther_mc._x = 50;
someOther_mc._y = 100;
someOther_mc.gotoAndStop(3);
The with statement is useful for accessing multiple items in a scope chain list simultaneously. In
the following example, the built-in Math object is placed at the front of the scope chain. Setting
Math as a default object resolves the identifiers cos, sin, and PI to Math.cos, Math.sin, and
Math.PI, respectively. The identifiers a, x, y, and r are not methods or properties of the Math
object, but because they exist in the object activation scope of the function polar(), they resolve
to the corresponding local variables.
function polar(r:Number):Void {
var a:Number, x:Number, y:Number;
with (Math) {
a = PI*pow(r, 2);
x = r*cos(PI);
y = r*sin(PI/2);
}
trace("area = "+a);
trace("x = "+x);
trace("y = "+y);
}
polar(3);
The following result is displayed in the Output panel.
area = 28.2743338823081
x = -3
y = 3
See also
tellTarget
1008 Chapter 2: ActionScript Language Reference

CHAPTER 2
ActionScript Language Reference
XML class
Availability
Flash Player 5 (became a native object in Flash Player 6, which improved
performance significantly).
Description
Use the methods and properties of the XML class to load, parse, send, build, and manipulate
XML document trees.
You must use the constructor new XML() to create an XML object before calling any method of
the XML class.
An XML document is represented in Flash by the XML class. Each element of the hierarchical
document is represented by an XMLNode object.
Note: The XML and XMLNode objects are modeled after the W3C DOM Level 1 recommendation:
www.w3.org/TR/1998/REC-DOM-Level-1-19981001/level-one-core.html. That recommendation
specifies a Node interface and a Document interface. The Document interface inherits from the Node
interface, and adds methods such as createElement() and createTextNode(). In ActionScript, the
XML and XMLNode objects are designed to divide functionality along similar lines.
Method summary for the XML class
Method Description
XML.addRequestHeader() Adds or changes HTTP headers for POST operations.
XML.appendChild() Appends a node to the end of the specified object’s child list.
XML.cloneNode() Clones the specified node and, optionally, recursively clones all children.
XML.createElement() Creates a new XML element.
XML.createTextNode() Creates a new XML text node.
XML.getBytesLoaded() Returns the number of bytes loaded for the specified XML document.
XML.getBytesTotal() Returns the size of the XML document, in bytes.
XML.hasChildNodes() Returns true if the specified node has child nodes; otherwise, returns
false.
XML.insertBefore() Inserts a node in front of an existing node in the specified node’s child list.
XML.load() Loads a document (specified by the XML object) from a URL.
XML.parseXML() Parses an XML document into the specified XML object tree.
XML.removeNode() Removes the specified node from its parent.
XML.send() Sends the specified XML object to a URL.
XML.sendAndLoad() Sends the specified XML object to a URL, and loads the server response
into another XML object.
XML.toString() Converts the specified node and any children to XML text.
XML class 1009

Property summary for the XML class
Property Description
XML.contentType The MIME type transmitted to the server.
XML.docTypeDecl Sets and returns information about an XML document’s
DOCTYPE declaration.
XML.firstChild Read-only; references the first child in the list for the specified node.
XML.ignoreWhite When set to true, discards, during the parsing process, text nodes that
contain only white space.
XML.lastChild Read-only; references the last child in the list for the specified node.
XML.loaded Read-only; checks whether the specified XML object has loaded.
XML.nextSibling Read-only; references the next sibling in the parent node’s child list.
XML.nodeName The node name of an XML object.
XML.nodeType The type of the specified node (XML element or text node).
XML.nodeValue The text of the specified node if the node is a text node.
XML.parentNode Read-only; references the parent node of the specified node.
XML.previousSibling Read-only; references the previous sibling in the parent node’s child list.
XML.status A numeric status code that indicates the success or failure of an XML
document parsing operation.
XML.xmlDecl Specifies information about a document’s XML declaration.
Collections summary for the XML class
Method Description
XML.attributes Returns an associative array that contains all the attributes of the specified
node.
XML.childNodes Read-only; returns an array that contains references to the child nodes of
the specified node.
Event handler summary for the XML class
Event handler Description
XML.onData Invoked when XML text has been completely downloaded from the
server, or when an error occurs downloading XML text from a server.
XML.onLoad Returns a Boolean value indicating whether the XML object was
successfully loaded with XML.load() or XML.sendAndLoad().
1010 Chapter 2: ActionScript Language Reference

Constructor for the XML class
Availability
Flash Player 5.
Usage
new XML([source:String]) : XML
Parameters
source A string; the XML text parsed to create the new XML object.
Returns
A reference to an XML object.
Description
Constructor; creates a new XML object. You must use the constructor to create an XML object
before you call any of the methods of the XML class.
Note: Use the createElement() and createTextNode() methods to add elements and text nodes to
an XML document tree.
Example
The following example creates a new, empty XML object:
var my_xml:XML = new XML();
The following example creates an XML object by parsing the XML text specified in the source
parameter, and populates the newly created XML object with the resulting XML document tree:
var other_xml:XML = new XML("
San Francisco");
See also
XML.createElement(), XML.createTextNode()
XML class 1011

XML.addRequestHeader()
Availability
Flash Player 6.
Usage
my_xml.addRequestHeader(headerName:String, headerValue:String) : Void
my_xml.addRequestHeader(["headerName_1":String, "headerValue_1":String ...
"headerName_n":String, "headerValue_n":String]) : Void
Parameters
headerName A string that represents an HTTP request header name.
headerValue A string that represents the value associated with headerName.
Returns
Nothing.
Description
Method; adds or changes HTTP request headers (such as Content-Type or SOAPAction) sent
with POST actions. In the first usage, you pass two strings to the method: headerName and
headerValue. In the second usage, you pass an array of strings, alternating header names and
header values.
If multiple calls are made to set the same header name, each successive value replaces the value set
in the previous call.
You cannot add or change the following standard HTTP headers using this method:
Accept-Ranges, Age, Allow, Allowed, Connection, Content-Length, Content-Location,
Content-Range, ETag, Host, Last-Modified, Locations, Max-Forwards,
Proxy-Authenticate, Proxy-Authorization, Public, Range, Retry-After, Server, TE,
Trailer, Transfer-Encoding, Upgrade, URI, Vary, Via, Warning, and WWW-Authenticate.
Example
The following example adds a custom HTTP header named SOAPAction with a value of Foo to
an XML object named my_xml:
my_xml.addRequestHeader("SOAPAction", "'Foo'");
The following example creates an array named headers that contains two alternating HTTP
headers and their associated values. The array is passed as a parameter to the
addRequestHeader() method.
var headers:Array = new Array("Content-Type", "text/plain",
"X-ClientAppVersion", "2.0");
my_xml.addRequestHeader(headers);
See also
LoadVars.addRequestHeader()
1012 Chapter 2: ActionScript Language Reference

XML.appendChild()
Availability
Flash Player 5.
Usage
my_xml.appendChild(childNode:XMLNode) : Void
Parameters
childNode An XMLNode that represents the node to be moved from its current location to the
child list of the my_xml object.
Returns
Nothing.
Description
Method; appends the specified node to the XML object’s child list. This method operates directly
on the node referenced by the childNode parameter; it does not append a copy of the node. If the
node to be appended already exists in another tree structure, appending the node to the new
location will remove it from its current location. If the childNode parameter refers to a node that
already exists in another XML tree structure, the appended child node is placed in the new tree
structure after it is removed from its existing parent node.
Example
This example does the following things in the order shown:
• Creates two empty XML documents, doc1 and doc2.
• Creates a new node using the createElement() method, and appends it, using the
appendChild() method, to the XML document named doc1.
• Shows how to move a node using the appendChild() method, by moving the root node from
doc1 to doc2.
• Clones the root node from doc2 and appends it to doc1.
• Creates a new node and appends it to the root node of the XML document doc1.
var doc1:XML = new XML();
var doc2:XML = new XML();
// create a root node and add it to doc1
var rootnode:XMLNode = doc1.createElement("root");
doc1.appendChild(rootnode);
trace ("doc1: " + doc1); // output: doc1:
trace ("doc2: " + doc2); // output: doc2:
// move the root node to doc2
doc2.appendChild(rootnode);
trace ("doc1: " + doc1); // output: doc1:
trace ("doc2: " + doc2); // output: doc2:
// clone the root node and append it to doc1
XML.appendChild() 1013

XML.attributes
Availability
Flash Player 5.
Usage
my_xml.attributes:Array
Description
Property; an associative array that contains all the attributes of the specified XML object.
Associative arrays use keys as indexes, instead of the simple ordinal integer indexes used by regular
arrays. In the XML.attributes associative array, the key index is a string representing the name of
the attribute. The value associated with that key index is the string value associated with that
attribute. For example, if you have an attribute named color, you would retrieve that attribute’s
value by using the color as the key index, as the following code shows:
var myColor:String = doc.firstChild.attributes.color
Example
The following example shows the XML attribute names:
// create a tag called 'mytag' with
// an attribute called 'name' with value 'Val'
var doc:XML = new XML(" item ");
// assign the value of the 'name' attribute to variable y
var y:String = doc.firstChild.attributes.name;
trace (y); // output: Val
// create a new attribute named 'order' with value 'first'
doc.firstChild.attributes.order = "first";
// assign the value of the 'order' attribute to variable z
var z:String = doc.firstChild.attributes.order
trace(z); // output: first
The following is displayed in the Output panel:
Val
first
XML.attributes 1015

XML.childNodes
Availability
Flash Player 5.
Usage
my_xml.childNodes:Array
Description
Read-only property; an array of the specified XML object’s children. Each element in the array is
a reference to an XML object that represents a child node. This is a read-only property and
cannot be used to manipulate child nodes. Use the XML.appendChild(), XML.insertBefore(),
and XML.removeNode() methods to manipulate child nodes.
This property is undefined for text nodes (nodeType == 3).
Example
The following example shows how to use the XML.childNodes property to return an array of
child nodes:
// create a new XML document
var doc:XML = new XML();
// create a root node
var rootNode:XMLNode = doc.createElement("rootNode");
// create three child nodes
var oldest:XMLNode = doc.createElement("oldest");
var middle:XMLNode = doc.createElement("middle");
var youngest:XMLNode = doc.createElement("youngest");
// add the rootNode as the root of the XML document tree
doc.appendChild(rootNode);
// add each of the child nodes as children of rootNode
rootNode.appendChild(oldest);
rootNode.appendChild(middle);
rootNode.appendChild(youngest);
// create an array and use rootNode to populate it
var firstArray:Array = doc.childNodes;
trace (firstArray);
// output:
// create another array and use the child nodes to populate it
var secondArray:Array = rootNode.childNodes;
trace(secondArray);
// output: ,,
See also
XML.nodeType
1016 Chapter 2: ActionScript Language Reference

XML.cloneNode()
Availability
Flash Player 5.
Usage
my_xml.cloneNode(deep:Boolean) : XMLNode
Parameters
deep A Boolean value; if set to true, the children of the specified XML object will be
recursively cloned.
Returns
An XMLNode object.
Description
Method; constructs and returns a new XML node of the same type, name, value, and attributes as
the specified XML object. If deep is set to true, all child nodes are recursively cloned, resulting in
an exact copy of the original object’s document tree.
The clone of the node that is returned is no longer associated with the tree of the cloned item.
Consequently, nextSibling, parentNode, and previousSibling all have a value of null. If the
deep parameter is set to false, or the my_xml node has no child nodes, firstChild and
lastChild are also null.
Example
The following example shows how to use the XML.cloneNode() method to create a copy of a
node:
// create a new XML document
var doc:XML = new XML();
// create a root node
var rootNode:XMLNode = doc.createElement("rootNode");
// create three child nodes
var oldest:XMLNode = doc.createElement("oldest");
var middle:XMLNode = doc.createElement("middle");
var youngest:XMLNode = doc.createElement("youngest");
// add the rootNode as the root of the XML document tree
doc.appendChild(rootNode);
// add each of the child nodes as children of rootNode
rootNode.appendChild(oldest);
rootNode.appendChild(middle);
rootNode.appendChild(youngest);
// create a copy of the middle node using cloneNode()
var middle2:XMLNode = middle.cloneNode(false);
XML.cloneNode() 1017

XML.contentType
Availability
Flash Player 6.
Usage
my_xml.contentType:String
Description
Property; the MIME content type that is sent to the server when you call the XML.send() or
XML.sendAndLoad() method. The default is application/x-www-form-urlencoded, which is
the standard MIME content type used for most HTML forms.
Example
The following example creates a new XML document and checks its default content type:
// create a new XML document
var doc:XML = new XML();
// trace the default content type
trace(doc.contentType); // output: application/x-www-form-urlencoded
The following example defines an XML packet, and sets the content type for the XML object.
The data is then sent to a server and shows a result in a browser window.
var my_xml:XML = new XML("Ernie13045
");
my_xml.contentType = "text/xml";
my_xml.send("http://www.flash-mx.com/mm/highscore.cfm", "_blank");
Press F12 to test this example in a browser.
See also
XML.send(), XML.sendAndLoad()
XML.contentType 1019

XML.createElement()
Availability
Flash Player 5.
Usage
my_xml.createElement(name:String) : XMLNode
Parameters
name The tag name of the XML element being created.
Returns
An XMLNode; an XML element.
Description
Method; creates a new XML element with the name specified in the parameter. The new element
initially has no parent, no children, and no siblings. The method returns a reference to the newly
created XML object that represents the element. This method and the XML.createTextNode()
method are the constructor methods for creating nodes for an XML object.
Example
The following example creates three XML nodes using the createElement() method:
// create an XML document
var doc:XML = new XML();
// create three XML nodes using createElement()
var element1:XMLNode = doc.createElement("element1");
var element2:XMLNode = doc.createElement("element2");
var element3:XMLNode = doc.createElement("element3");
// place the new nodes into the XML tree
doc.appendChild(element1);
element1.appendChild(element2);
element1.appendChild(element3);
trace(doc);
// output:
See also
XML.createTextNode()
1020 Chapter 2: ActionScript Language Reference