The flash.utils package contains a variety of package-level functions for timing code execution, retrieving information about classes and objects, and converting escape characters.
| Function | Defined By | ||
|---|---|---|---|
Cancels a specified setInterval() call. | flash.utils | ||
Cancels a specified setTimeout() call. | flash.utils | ||
Produces an XML object that describes the ActionScript object named as the parameter of
the method. | flash.utils | ||
Returns an escaped copy of the input string encoded as either UTF-8 or system code page, depending on the value of System.useCodePage. | flash.utils | ||
Returns a reference to the class object of the class specified by the name parameter. | flash.utils | ||
Returns the fully qualified class name of an object. | flash.utils | ||
Returns the fully qualified class name of the base class of the object specified by the value
parameter. | flash.utils | ||
Used to compute relative time. | flash.utils | ||
Runs a function at a specified interval (in milliseconds). | flash.utils | ||
Runs a specified function after a specified delay (in milliseconds). | flash.utils | ||
Returns an unescaped copy of the input string, which is decoded from either system code page page or UTF-8 depending on the value of System.useCodePage. | flash.utils | ||
clearInterval | () | function |
public function clearInterval(id:uint):void| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9 |
Cancels a specified setInterval() call.
Parameters
id:uint — The ID of the setInterval() call, which you set to a variable,
as in the following:
|
Related API Elements
Example ( How to use this example )
setInterval() method to create a timed
interval, calling the myRepeatingFunction() method after regular intervals of one
second.
Each call of the myRepeatingFunction method increments the counter
property, and when it equals the stopCount property, the clearInterval()
method is called with the property intervalId which is a reference id to
the interval that was created earlier.
package {
import flash.display.Sprite;
import flash.utils.*;
public class ClearIntervalExample extends Sprite {
private var intervalDuration:Number = 1000; // duration between intervals, in milliseconds
private var intervalId:uint;
private var counter:uint = 0;
private var stopCount:uint = 3;
public function ClearIntervalExample() {
intervalId = setInterval(myRepeatingFunction, intervalDuration, "Hello", "World");
}
public function myRepeatingFunction():void {
trace(arguments[0] + " " + arguments[1]);
counter++;
if(counter == stopCount) {
trace("Clearing Interval");
clearInterval(intervalId);
}
}
}
}
clearTimeout | () | function |
public function clearTimeout(id:uint):void| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9 |
Cancels a specified setTimeout() call.
Parameters
id:uint — The ID of the setTimeout() call, which you set to a variable,
as in the following:
|
Related API Elements
Example ( How to use this example )
setTimeout() method to call another
method following a specified delay period.
A loop is created to count to one million. If the system can process this request faster
than a second can expire, clearTimeout() will remove the setTimeout()
request, and myDelayedFunction() will not be called.
package {
import flash.display.Sprite;
import flash.utils.*;
public class ClearTimeoutExample extends Sprite {
private var delay:Number = 1000; // delay before calling myDelayedFunction
private var intervalId:uint;
private var count:uint = 1000000;
public function ClearTimeoutExample() {
intervalId = setTimeout(myDelayedFunction, delay);
startCounting();
}
public function startCounting():void {
var i:uint = 0;
do {
if(i == count-1) {
clearTimeout(intervalId);
trace("Your computer can count to " + count + " in less than " + delay/1000 + " seconds.");
}
i++;
} while(i < count)
}
public function myDelayedFunction():void {
trace("Time expired.");
}
}
}
describeType | () | function |
public function describeType(value:*):XML| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Produces an XML object that describes the ActionScript object named as the parameter of the method. This method implements the programming concept of reflection for the ActionScript language.
If the value parameter is an instance of a type, the returned XML object includes all the instance properties of that type,
but does not include any static properties. You can check for this condition when you parse the XML object by examining the value of the <type> tag's isStatic attribute, which is false when the value parameter is an instance of a type.
To obtain the static properties of a type, pass the type itself for the value parameter. The returned XML object includes not only the type's static properties, but also all of its instance properties.
The instance properties are nested inside a tag named <factory> to distinguish them from the static properties.
In this case, the isStatic attribute of the <type> tag is true.
Note: If you need only to traverse an object's inheritance hierarchy and do not need the other information provided by describeType(),
use the getQualifiedClassName() and getQualifiedSuperclassName() functions instead.
The following table describes some of the tags and attributes of the XML object generated by describeType()
(all class and interface names returned are in fully qualified format):
| Tag | Attribute | Description |
|---|---|---|
<type> | The root tag of the XML object. | |
| name | The name of the ActionScript object's data type. | |
| base | The immediate superclass of the ActionScript object's defining class. If the ActionScript object is a class object, the value is Class. | |
| isDynamic | true if the ActionScript object's defining class is dynamic; false otherwise. If the ActionScript object is a class object, the value is true because the Class class is dynamic. | |
| isFinal | true if the ActionScript object's defining class is final; false otherwise. | |
| isStatic | true if the ActionScript object is a class object or constructor function; false otherwise. This attribute is named isStatic because if it is true, any tags that are not nested inside the factory tag are static. | |
<extendsClass> | There is a separate extendsClass tag for each superclass of the ActionScript object's defining class. | |
| type | The name of a superclass that the ActionScript object's defining class extends. | |
<implementsInterface> | There is a separate implementsInterface tag for each interface implemented by the ActionScript object's defining class or any of its superclasses. | |
| type | The name of an interface that the ActionScript object's defining class implements. | |
<accessor> | An accessor is a property defined by getter and setter functions. | |
| name | The name of the accessor. | |
| access | The access rights of the property. Possible values include readonly, writeonly, and readwrite. | |
| type | The data type of the property. | |
| declaredBy | The class that contains the associated getter or setter functions. | |
<constant> | A constant is a property defined with the const statement. | |
| name | The name of the constant. | |
| type | The data type of the constant. | |
<method> | A method is a function declared as part of a class definition. | |
| name | The name of the method. | |
| declaredBy | The class that contains the method definition. | |
| returnType | The data type of the method's return value. | |
<parameter> | There is a separate parameter tag for each parameter that a method defines. This tag is always nested inside a <method> tag. | |
| index | A number corresponding to the order in which the parameter appears in the method's parameter list. The first parameter has a value of 1. | |
| type | The data type of the parameter. | |
| optional | true if the parameter is optional; false otherwise. | |
<variable> | A variable is a property defined with the var statement. | |
| name | The name of the variable. | |
| type | The data type of the variable. | |
<factory> | If the ActionScript object is a class object or constructor function, all instance properties and methods are nested inside this tag. If the isStatic attribute of the <type> tag is true, all properties and methods that are not nested within the <factory> tag are static. This tag appears only if the ActionScript object is a class object or constructor function. |
Parameters
value:* — The object for which a type description is desired. Any ActionScript value
may be passed to this method including all available ActionScript types, object
instances, primitive types such as uint, and class objects.
|
XML — An XML object containing details about the object that was passed in as a parameter.
It provides the following information about the object:
Note: |
Related API Elements
Example ( How to use this example )
package {
import flash.display.Sprite;
import flash.utils.describeType;
public class DescribeTypeExample extends Sprite {
public function DescribeTypeExample() {
var child:Sprite = new Sprite();
var description:XML = describeType(child);
trace(description..accessor.@name.toXMLString());
}
}
}
escapeMultiByte | () | function |
public function escapeMultiByte(value:String):String| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Returns an escaped copy of the input string encoded as either UTF-8 or system code page, depending on the value of System.useCodePage.
Use of System.useCodePage allows legacy content encoded in local code pages to be accessed by the runtime, but only on systems using that legacy code page.
For example, Japanese data encoded as Shift-JIS will only be escaped and unescaped properly on an OS using a Japanese default code page.
Parameters
value:String — The string to be escaped.
|
String — An escaped copy of the input string. If System.useCodePage is true, the escaped string is encoded in the system code page.
If System.useCodePage is false, the escaped string is encoded in UTF-8.
For example, the input string "Crüe" will be escaped as "Cr%C3%BCe" on all systems if System.useCodePage is false.
If system.useCodePage is true, and the system uses a Latin code page, "Crüe" will be escaped as "Cr%FCe".
If the system uses a non Latin code page that does not contain the letter 'ü' the result will probably be "Cr?e".
Unescaping "Cr%C3%BCe" with System.useCodePage set to true will produce different undesired results on different systems, such as "Crüe" on a Latin system.
Similarly, unescaping "Cr%FCe" with System.useCodePage set to false could produce "Cre" or "Cr?e" or other variations depending on the code page of the system.
|
getDefinitionByName | () | function |
public function getDefinitionByName(name:String):Object| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Returns a reference to the class object of the class specified by the name parameter.
Parameters
name:String — The name of a class.
|
Object — Returns a reference to the class object of the class specified by the name parameter.
|
Throws
ReferenceError — No public definition exists with the
specified name.
|
Example ( How to use this example )
GetDefinitionByNameExample to
create an orange square on the stage. This is accomplished using the following steps:
- Variables for the background color of orange and size of 80 pixels are declared, which will later be used in drawing the square.
- Within the constructor, a variable
ClassReferenceof type Class is assigned to Sprite. - An instance of ClassReference called
instanceis instantiated. - Since
instanceis, by reference, a Sprite object, a square can be drawn and added to the display list using the methods available to Sprite.
package {
import flash.display.DisplayObject;
import flash.display.Sprite;
import flash.utils.getDefinitionByName;
public class GetDefinitionByNameExample extends Sprite {
private var bgColor:uint = 0xFFCC00;
private var size:uint = 80;
public function GetDefinitionByNameExample() {
var ClassReference:Class = getDefinitionByName("flash.display.Sprite") as Class;
var instance:Object = new ClassReference();
instance.graphics.beginFill(bgColor);
instance.graphics.drawRect(0, 0, size, size);
instance.graphics.endFill();
addChild(DisplayObject(instance));
}
}
}
getQualifiedClassName | () | function |
public function getQualifiedClassName(value:*):String| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Returns the fully qualified class name of an object.
Parameters
value:* — The object for which a fully qualified class name is desired. Any ActionScript value
may be passed to this method including all available ActionScript types, object
instances, primitive types such as uint, and class objects.
|
String — A string containing the fully qualified class name.
|
Related API Elements
getQualifiedSuperclassName | () | function |
public function getQualifiedSuperclassName(value:*):String| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Returns the fully qualified class name of the base class of the object specified by the value
parameter. This function provides a quicker way of retrieving the base class name than describeType(), but also
doesn't provide all the information describeType() does.
After you retrieve the name of a class with this function, you can convert the class name to a class reference with the getDefinitionByName() function.
Note: This function restricts itself to instance hierarchies, whereas the describeType() function
uses class object hierarchies if the value parameter is a data type. Calling describeType() on a data type returns the
superclass based on the class object hierarchy, in which all class objects inherit from Class. The getQualifiedSuperclassName()
function, however, ignores the class object hierarchy and returns the superclass based on the more familiar instance hierarchy.
For example, calling getQualifiedSuperclassName(String)
returns Object although technically the String class object inherits from Class. In other words, the results are
the same whether you use an instance of a type or the type itself.
Parameters
value:* — Any value.
|
String — A fully qualified base class name, or null if none exists.
|
Related API Elements
getTimer | () | function |
public function getTimer():int| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Used to compute relative time. For a Flash runtime processing ActionScript 3.0, this method returns the number of milliseconds that have elapsed
since the Flash runtime virtual machine for ActionScript 3.0 (AVM2) started. For a Flash runtime processing ActionScript 2.0, this method returns
the number of milliseconds since the Flash runtime began initialization. Flash runtimes use two
virtual machines to process ActionScript. AVM1 is the ActionScript virtual machine used to run ActionScript 1.0 and 2.0.
AVM2 is the ActionScript virtual machine used to run ActionScript 3.0. The getTimer() method behavior for AVM1 is different than the
behavior for AVM2.
For a calendar date (timestamp), see the Date object.
Returnsint — The number of milliseconds since the runtime was initialized (while processing ActionScript 2.0), or since the virtual machine started (while
processing ActionScript 3.0). If the runtime starts playing one
SWF file, and another SWF file is loaded later, the return value is relative to when the first SWF file was
loaded.
|
Related API Elements
Example ( How to use this example )
GetTimerExample to get and print the
number of milliseconds since the runtime initialized.
package {
import flash.utils.getTimer;
import flash.display.Sprite;
public class GetTimerExample extends Sprite {
public function GetTimerExample() {
var duration:uint = getTimer();
trace("duration: " + duration);
}
}
}
setInterval | () | function |
public function setInterval(closure:Function, delay:Number, ... arguments):uint| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9 |
Runs a function at a specified interval (in milliseconds).
Instead of using the setInterval() method, consider
creating a Timer object, with the specified interval, using 0 as the repeatCount
parameter (which sets the timer to repeat indefinitely).
If you intend to use the clearInterval() method to cancel the
setInterval() call, be sure to assign the setInterval() call to a
variable (which the clearInterval() function will later reference).
If you do not call the clearInterval() function to cancel the
setInterval() call, the object containing the set timeout closure
function will not be garbage collected.
Parameters
closure:Function — The name of the function to execute. Do not include quotation marks or
parentheses, and do not specify parameters of the function to call. For example, use
functionName, not functionName() or functionName(param).
| |
delay:Number — The interval, in milliseconds.
| |
... arguments — An optional list of arguments that are passed to the closure function.
|
uint — Unique numeric identifier for the timed process. Use this identifier to cancel
the process, by calling the clearInterval() method.
|
Related API Elements
Example ( How to use this example )
setInterval() method to create a timed
interval, calling the myRepeatingFunction() method after regular intervals of one
second.
package {
import flash.display.Sprite;
import flash.utils.*;
public class SetIntervalExample extends Sprite {
private var intervalDuration:Number = 1000; // duration between intervals, in milliseconds
public function SetIntervalExample() {
var intervalId:uint = setInterval(myRepeatingFunction, intervalDuration, "Hello", "World");
}
public function myRepeatingFunction():void {
trace(arguments[0] + " " + arguments[1]);
}
}
}
setTimeout | () | function |
public function setTimeout(closure:Function, delay:Number, ... arguments):uint| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9 |
Runs a specified function after a specified delay (in milliseconds).
Instead of using this method, consider
creating a Timer object, with the specified interval, using 1 as the repeatCount
parameter (which sets the timer to run only once).
If you intend to use the clearTimeout() method to cancel the
setTimeout() call, be sure to assign the setTimeout() call to a
variable (which the clearTimeout() function will later reference).
If you do not call the clearTimeout() function to cancel the
setTimeout() call, the object containing the set timeout closure
function will not be garbage collected.
Parameters
closure:Function — The name of the function to execute. Do not include quotation marks or
parentheses, and do not specify parameters of the function to call. For example, use
functionName, not functionName() or functionName(param).
| |
delay:Number — The delay, in milliseconds, until the function is executed.
| |
... arguments — An optional list of arguments that are passed to the closure function.
|
uint — Unique numeric identifier for the timed process. Use this identifier to cancel
the process, by calling the clearTimeout() method.
|
Related API Elements
Example ( How to use this example )
setTimeout() method to call another
method following a specified delay period.
package {
import flash.display.Sprite;
import flash.utils.*;
public class SetTimeoutExample extends Sprite {
private var delay:Number = 1000; // delay before calling myDelayedFunction
public function SetTimeoutExample() {
var intervalId:uint = setTimeout(myDelayedFunction, delay, "Hello", "World");
}
public function myDelayedFunction():void {
trace(arguments[0] + " " + arguments[1]);
}
}
}
unescapeMultiByte | () | function |
public function unescapeMultiByte(value:String):String| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Returns an unescaped copy of the input string, which is decoded from either system code page page or UTF-8 depending on the value of System.useCodePage.
Use of System.useCodePage allows legacy content encoded in local code pages to be accessed by the runtime, but only on systems using that legacy code page.
For example, Japanese data encoded as Shift-JIS will only be escaped and unescaped properly on an OS using a Japanese default code page.
Parameters
value:String — The escaped string to be unescaped.
|
String — An unescaped copy of the input string. If System.useCodePage is true, the escaped string is decoded from the system code page.
If System.useCodePage is false, the escaped string is decoded from UTF-8.
For example, if the input string is "Crüe" and System.useCodePage is false, the result will be "Crüe" on all systems.
If System.useCodePage is true and the input string is "Cr%FCe", and the system uses a Latin code page, the result will also be "Crüe".
Unescaping "Cr%C3%BCe" with System.useCodePage set to true will produce different undesired results on different systems, such as "Crüe" on a Latin system.
Similarly, unescaping "Cr%FCe" with System.useCodePage set to false could produce "Cre" or "Cr?e" or other variations depending on the code page of the system.
|
Mon Nov 28 2011, 07:46 AM -08:00