Macromedia Logo

ActionScript 2.0 Language Reference

Global Properties

Global properties are available in every script, and are visible to every Timeline and scope in your document. For example, global properties allow access to the timelines of other loaded movie clips, both relative (_parent) and absolute (_root). They also let you restrict (this) or expand (super) scope. And, you can use global properties to adjust runtime settings like screen reader accessibility, playback quality, and sound buffer size.


Properties
       _accProps
Lets you control screen reader accessibility options for SWF files, movie clips, buttons, dynamic text fields, and input text fields at runtime.Property; lets you control screen reader accessibility options at runtime for SWF files and movie clips as well as for Button, TextArea, and TextInput controls.
       _focusrect
Property (global); specifies whether a yellow rectangle appears around the button or movie clip that has keyboard focus.
       _global
A reference to the global object that holds the core ActionScript classes, such as String, Object, Math, and Array.
       _highquality
Deprecated as of Flash Player 5 — This property was deprecated in favor of _quality.
       _level
A reference to the root Timeline of _level N.
       maxscroll  [read-only]
Deprecated as of Flash Player 5 — This property was deprecated in favor of TextField.maxscroll.
       _parent
Specifies or returns a reference to the movie clip or object that contains the current movie clip or object.
       _quality
Sets or retrieves the rendering quality used for a movie clip.
       _root
Specifies or returns a reference to the root movie clip Timeline.
       scroll
Deprecated as of Flash Player 5 — This property was deprecated in favor of TextField.scroll.
       _soundbuftime
Establishes the number of seconds of streaming sound to buffer.
       this
References an object or movie clip instance.


Property detail

_accProps Property

_accProps.propertyName
instanceName._accProps.propertyName

Player version:  Flash Player 6,0,65,0

Lets you control screen reader accessibility options for SWF files, movie clips, buttons, dynamic text fields, and input text fields at runtime. Lets you control screen reader accessibility options at runtime for SWF files and movie clips as well as for Button, TextArea, and TextInput controls. These properties override the corresponding settings available in the Accessibility panel during authoring. For changes to these properties to take effect, you must call Accessibility.updateProperties().

For information on the Accessibility panel, see "The Flash Accessibility panel" in Using Flash.

To determine whether the player is running in an environment that supports accessibility aids, use the System.capabilities.hasAccessibility() method .

The following table lists the name and data type of each _accProps property , its equivalent setting in the Accessibility panel, and the kinds of objects to which the property can be applied. The term inverse logic means that the property setting is the inverse of the corresponding setting in the Accessibility panel. For example, setting the silent property to true is equivalent to deselecting the Make Movie Accessible or Make Object Accessible option.

Property Data type Equivalent in Accessibility panel Applies to
silent Boolean Make Movie Accessible/
Make Object Accessible (inverse logic)
Whole SWF files
Movie clips
Buttons
Dynamic text
Input text
forceSimple Boolean Make Child Objects Accessible (inverse logic) Whole SWF files
Movie clips
name String Name Whole SWF files
Movie clips
Buttons
Input text
description String Description Whole SWF files
Movie clips
Buttons
Dynamic text
Input text
shortcut String Shortcut Movie clips
Buttons
Input text

For the Shortcut field, use names of the form Control+A. Adding a keyboard shortcut to the Accessibility panel doesn't create a keyboard shortcut; it merely advises screen readers of an existing shortcut. For information on assigning a keyboard shortcut to an accessible object, see Key.addListener().

Property Data type Applies to
silent Boolean Whole SWF files
Movie clips
Buttons
Dynamic text
Input text
forceSimple Boolean Whole SWF files
Movie clips
name String Whole SWF files
Movie clips
Buttons
Input text
description String Whole SWF files
Movie clips
Buttons
Dynamic text
Input text
shortcut String Movie clips
Buttons
Input text

To specify settings that correspond to the Tab index setting in the Accessibility panel, use the Button.tabIndex, MovieClip.tabIndex, or TextField.tabIndex properties.

There is no way to specify an Auto Label setting at runtime.

To refer to the _accProps object that represents the entire Flash document, omit the instanceName parameter. The value of _accProps must be an object. This means that if no _accProps object already exists, you must create one, as shown in the following example, before you can assign values to the properties of the _accProps object:

if ( _accProps == undefined ) { _accProps = new Object(); } _accProps.name = "My SWF file";

When _accProps is used without the instanceName parameter, changes made to _accProps properties apply to the whole SWF file. For example, the following code sets the Accessibility name property for the whole SWF file to the string "Pet Store" and then calls Accessibility.updateProperties() to cause that change:

_accProps.name = "Pet Store"; Accessibility.updateProperties();

In contrast, the following code sets the name property for a movie clip with the instance name price_mc to the string "Price":

price_mc._accProps.name = "Price"; Accessibility.updateProperties();

If you are specifying several accessibility properties, make as many changes as you can before calling Accessibility.updateProperties(), instead of calling it after each property statement, as shown in the following example:

_accProps.name = "Pet Store"; animal_mc._accProps.name = "Animal"; animal_mc._accProps.description = "Cat, dog, fish, etc."; price_mc._accProps.name = "Price"; price_mc._accProps.description = "Cost of a single item"; Accessibility.updateProperties();

If you don't specify an accessibility property for a document or an object, any values set in the Accessibility panel are implemented.

After you specify an accessibility property, you can't revert its value to a value set in the Accessibility panel. However, you can set the property to its default value (false for Boolean values; empty strings for string values) by deleting the property from the _accProps object, as shown in the following example: my_mc._accProps.silent = true; // set a property // other code here delete my_mc._accProps.silent; // revert to default value

The value of _accProps must be an object. This means that if no _accProps object already exists, you must create one before you can assign clues to the properties of the _accProps object.

if (_accProps == undefined) { _accProps = new Object(); } _accProps.name = "My movie";
In the following example, to revert a property to its default value (false for Boolean values, empty strings for String values), delete the property from the _accProps object: my_mc._accProps.silent = true; // set a property // other code here delete my_mc._accProps.silent; // revert to default value

Example
If you change an image and want to update its accessibility description, you can use the following ActionScript code:
my_mc.gotoAndStop(2);

if (my_mc._accProps == undefined ) {
    my_mc._accProps = new Object();
}

my_mc._accProps.name = "Photo of Mount Rushmore";
Accessibility.updateProperties();

See also
    Accessibility.isActive(), Accessibility.updateProperties(), System.capabilities.hasAccessibility


_focusrect Property

_focusrect = Boolean;

Player version:  Flash Player 4

Specifies whether a yellow rectangle appears around the button or movie clip that has keyboard focus. If _focusrect is set to its default value of true, then a yellow rectangle appears around the currently focused button or movie clip as the user presses the Tab key to navigate through objects in a SWF file. Specify false if you do not want to show the yellow rectangle. This is a global property that can be overridden for specific instances.

If the global _focusrect property is set to false, then the default behavior for all buttons and movieclips is that keyboard navigation is limited to the Tab key. All other keys, including the Enter and arrow keys, are ignored. To restore full keyboard navigation, you must set _focusrect to true. To restore full keyboard functionality for a specific button or movieclip, you can override this global property using either Button._focusrect or MovieClip._focusrect.

Note: If you use a component, then FocusManager overrides Flash Player's focus handling, including use of this global property.

Example
The following example demonstrates how to hide the yellow rectangle around any instances in a SWF file when they have focus in a browser window. Create some buttons or movie clips and add the following ActionScript in frame 1 of the Timeline:
_focusrect = false;
Change the publish settings to Flash Player 6, and test the SWF file in a browser window by selecting File > Publish Preview > HTML. Give the SWF focus by clicking it in the browser window, and use the Tab key to focus each instance. Pressing Enter or the Space key when _focusrect is disabled does not invoke the onRelease event handler as it does when _focusrect is enabled or true.

See also
    Button._focusrect, MovieClip._focusrect


_global Property

_global.identifier

Player version:  Flash Player 6

A reference to the global object that holds the core ActionScript classes, such as String, Object, Math, and Array. For example, you could create a library that is exposed as a global ActionScript object, similar to the Math or Date object. Unlike Timeline-declared or locally declared variables and functions, global variables and functions are visible to every Timeline and scope in the SWF file, provided they are not obscured by identifiers with the same names in inner scopes. Unlike locally declared variables and functions, global variables and functions are visible to every scope in the SWF file, provided they are not obscured by identifiers with the same names in inner scopes.

Note: When setting the value of a global variable, you must use the fully qualified name of the variable, e.g. _global.variableName. Failure to do so will create a local variable of the same name that obscures the global variable you are attempting to set.

Returns
A reference to the global object that holds the core ActionScript classes, such as String, Object, Math, and Array.

Example
The following example creates a top-level function, factorial(), that is available to every Timeline and scope in a SWF file:

The following example creates a top-level function factorial() that is available to every scope in a SWF file:

_global.factorial = function(n:Number) {
    if(n <= 1) {
        return 1;
    } 
    else {
        return n * factorial(n - 1);
    }
}

trace(factorial(1)); // 1
trace(factorial(2)); // 2
trace(factorial(3)); // 6
trace(factorial(4)); // 24

The following example shows how the failure to use the fully qualified variable name when setting the value of a global variable leads to unexpected results:

_global.myVar = "globalVariable";
trace(_global.myVar);    // globalVariable
trace(myVar);        // globalVariable

myVar = "localVariable";
trace(_global.myVar);    // globalVariable
trace(myVar);        // localVariable

See also
    var statement, set variable statement


_highquality Property

_highquality

Deprecated as of Flash Player 5 — This property was deprecated in favor of _quality.

Player version:  Flash Player 4

Specifies the level of anti-aliasing applied to the current SWF file. Specify 2 (best quality) to apply high quality with bitmap smoothing always on. Specify 1 (high quality) to apply anti-aliasing; this will smooth bitmaps if the SWF file does not contain animation. Specify 0 (low quality) to prevent anti-aliasing.

Example
The following ActionScript is placed on the main Timeline, and sets the global quality property to always apply bitmap smoothing in non-animated files.
_highquality = 1;

See also
    _quality


_level Property

_levelN

Player version:  Flash Player 4

A reference to the root Timeline of _level N. You must use loadMovieNum() to load SWF files into the Flash Player before you use the _level property to target them. You can also use _level N to target a loaded SWF file at the level assigned by N.

The initial SWF file loaded into an instance of the Flash Player is automatically loaded into _level0. The SWF file in _level0 sets the frame rate, background color, and frame size for all subsequently loaded SWF files. SWF files are then stacked in higher-numbered levels above the SWF file in _level0.

You must assign a level to each SWF file that you load into the Flash Player using loadMovieNum(). You can assign levels in any order. If you assign a level that already contains a SWF file (including _level0), the SWF file at that level is unloaded and replaced by the new SWF file.

Example
The following example stops the playhead in the main Timeline of the SWF file sub.swf that is loaded into _level9. The sub.swf file contains animation and is in the same directory as the document that contains the following ActionScript:

loadMovieNum("sub.swf", 9);
myBtn_btn.onRelease = function() {
    _level9.stop();
};

You could replace _level9.stop() in the previous example with the following code:

_level9.gotoAndStop(5);

This action sends the playhead in the main Timeline of the SWF file in _level9 to Frame 5 instead of stopping the playhead.

See also
    loadMovie() function, MovieClip.swapDepths()


maxscroll Property

variable_name.maxscroll

Deprecated as of Flash Player 5 — This property was deprecated in favor of TextField.maxscroll.

Player version:  Flash Player 4

Indicates the line number of the top line of visible text in a text field when the bottom line in the field is also visible. The maxscroll property works with the scroll property to control how information appears in a text field. This property can be retrieved, but not modified.

See also
    TextField.maxscroll, TextField.scroll


_parent Property

_parent.property
_parent._parent.property

Player version:  Flash Player 5

Specifies or returns a reference to the movie clip or object that contains the current movie clip or object. The current object is the object containing the ActionScript code that references _parent. Use _parent to specify a relative path to movie clips or objects that are above the current movie clip or object.

Example
In the following example, there is a movie clip on the Stage with the instance name square_mc. Within that movie clip is another movie clip with an instance name circle_mc. The following ActionScript lets you modify the circle_mc parent instance (which is square_mc) when the circle is clicked. When you are working with relative addressing (using _parent instead of _root), it might be easier to use the Insert Target Path button in the Actions panel at first.
this.square_mc.circle_mc.onRelease = function() {
    this._parent._alpha -= 5;
};

See also
    _root, targetPath() function


_quality Property

_quality:String

Player version:  Flash Player 5

Sets or retrieves the rendering quality used for a movie clip. Device fonts are always aliased and therefore are unaffected by the _quality property.

The _quality property can be set to the values described in the following table.

Value Description Graphic Anti-Aliasing Bitmap Smoothing
"LOW" Low rendering quality. Graphics are not anti-aliased. Bitmaps are not smoothed.
"MEDIUM" Medium rendering quality. This setting is suitable for movies that do not contain text. Graphics are anti-aliased using a 2 x 2 pixel grid. Flash Player 8: Bitmaps are smoothed based on the smoothing parameter used in MovieClip.attachBitmap() and MovieClip.beginBitmapFill() calls.

Flash Player 6 and 7: Bitmaps are not smoothed.

"HIGH" High rendering quality. This setting is the default rendering quality setting that Flash uses. Graphics are anti-aliased using a 4 x 4 pixel grid. Flash Player 8: Bitmaps are smoothed based on the smoothing parameter used in MovieClip.attachBitmap() and MovieClip.beginBitmapFill() calls.

Flash Player 6 and 7: Bitmaps are smoothed if the movie clip is static.

"BEST" Very high rendering quality. Graphics are anti-aliased using a 4 x 4 pixel grid. Flash Player 8: Bitmaps are smoothed based on the smoothing parameter used in MovieClip.attachBitmap() and MovieClip.beginBitmapFill() calls. When smoothing is set to "Best", the result is rendered with higher quality when the movie clip is scaled down by the use of an averaging algorithm. This can slow down rendering, but it allows high-quality thumbnails of large images, for example.

Flash Player 6 and 7: Bitmaps are always smoothed.

Example
The following example sets the rendering quality to LOW:
_quality = "LOW";


_root Property

_root.movieClip
_root.action
_root.property

Player version:  Flash Player 5

Specifies or returns a reference to the root movie clip Timeline. If a movie clip has multiple levels, the root movie clip Timeline is on the level containing the currently executing script. For example, if a script in level 1 evaluates _root , _level1 is returned.

Specifying _root is the same as using the deprecated slash notation (/) to specify an absolute path within the current level.

Note: If a movie clip that contains _root is loaded into another movie clip, _root refers to the Timeline of the loading movie clip, not the Timeline that contains _root. If you want to ensure that _root refers to the Timeline of the loaded movie clip even if it is loaded into another movie clip, use MovieClip._lockroot.

Example
The following example stops the Timeline of the level containing the currently executing script:
_root.stop();
The following example traces variables and instances in the scope of _root:
for (prop in _root) {
    trace("_root."+prop+" = "+_root[prop]);
}

See also
    MovieClip._lockroot, _parent, targetPath()


scroll Property

textFieldVariableName.scroll = x

Deprecated as of Flash Player 5 — This property was deprecated in favor of TextField.scroll.

Player version:  Flash Player 4

Controls the display of information in a text field associated with a variable. The scroll property defines where the text field begins displaying content; after you set it, Flash Player updates it as the user scrolls through the text field. The scroll property is useful for directing users to a specific paragraph in a long passage or creating scrolling text fields. This property can be retrieved and modified.

Example
The following code is attached to an Up button that scrolls the text field named myText:
    
    on (release) {
        myText.scroll = myText.scroll + 1;
    }
    

See also
    TextField.maxscroll, TextField.scroll


_soundbuftime Property

_soundbuftime:Number = integer

Player version:  Flash Player 4

Establishes the number of seconds of streaming sound to buffer. The default value is 5 seconds.

Example
The following example streams an MP3 file and buffers the sound before it plays for the user. Two text fields are created at runtime to hold a timer and debugging information. The _soundbuftime property is set to buffer the MP3 for 10 seconds. A new Sound object instance is created for the MP3.
// create text fields to hold debug information.
this.createTextField("counter_txt", this.getNextHighestDepth(), 0, 0, 100, 22);
this.createTextField("debug_txt", this.getNextHighestDepth(), 0, 20, 100, 22);
// set the sound buffer to 10 seconds.
_soundbuftime = 10;
// create the new sound object instance.
var bg_sound:Sound = new Sound();
// load the MP3 sound file and set streaming to true.
bg_sound.loadSound("yourSound.mp3", true);
// function is triggered when the song finishes loading.
bg_sound.onLoad = function() {
    debug_txt.text = "sound loaded";
};
debug_txt.text = "sound init";
function updateCounter() {
    counter_txt.text++;
}
counter_txt.text = 0;
setInterval(updateCounter, 1000);


this Property

this

Player version:  Flash Player 5

References an object or movie clip instance. When a script executes, this references the movie clip instance that contains the script. When a method is called, this contains a reference to the object that contains the called method.

Identifier; refers to the object in the currently executing scope. If you are in a method and you want a reference to the object instance, use the this identifier. You can also use the this identifier to pass a class instance as an argument of a method to itself or another class.

Inside an on() event handler attached to a button, this refers to the Timeline that contains the button. Inside an onClipEvent() event handler attached to a movie clip, this refers to the Timeline of the movie clip itself.

Because this is evaluated in the context of the script that contains it, you can't use this in a script to refer to a variable defined in a class file.

Example
Create an ActionsScript file named ApplyThis.as and then enter the following code:
class ApplyThis {
    var str:String = "Defined in ApplyThis.as";
    function conctStr(x:String):String {
        return x+x;
    }
    function addStr():String {
        return str;
    }
}

Then, in a FLA or a separate ActionScript file, add the following code

var obj:ApplyThis = new ApplyThis();
var abj:ApplyThis = new ApplyThis();
abj.str = "defined in FLA or AS";
trace(obj.addStr.call(abj, null));  //output: defined in FLA or AS
trace(obj.addStr.call(this, null));  //output: undefined
trace(obj.addStr.call(obj, null));  //output: Defined in applyThis.as

Similarly, to call a function defined in a dynamic class, you must use this to invoke the function in the proper scope:

// incorrect version of Simple.as
/*
dynamic class Simple {
    function callfunc() {
        trace(func());
    }
}
*/
// correct version of Simple.as
dynamic class simple {
    function callfunc() {
        trace(this.func());
    }
}

Inside the FLA or a separate ActionScript file, add the following code:

var obj:Simple = new Simple();
obj.num = 0;
obj.func = function() {
    return true;
};
obj.callfunc();
// output: true

The above code works when you use this in the callfunc() method. However you would get a syntax error if you used the incorrect version of Simple.as, which was commented out in the above example.

In the following example, the keyword this references the Circle object:
function Circle(radius:Number):Void {
    this.radius = radius;
    this.area = Math.PI*Math.pow(radius, 2);
}
var myCircle = new Circle(4);
trace(myCircle.area);

In the following statement assigned to a frame inside a movie clip, the keyword this references the current movie clip.

// sets the alpha property of the current movie clip to 20
this._alpha = 20;

In the following statement inside a MovieClip.onPress handler, the keyword this references the current movie clip:

this.square_mc.onPress = function() {
    startDrag(this);
};
this.square_mc.onRelease = function() {
    stopDrag();
};

See also
    on() function, onClipEvent() function