PackageTop Level
Classpublic class Button
InheritanceButton Inheritance Object

Player version: Flash Player 6

All button symbols in a SWF file are instances of the Button object. You can give a button an instance name in the Property inspector, and use the methods and properties of the Button class to manipulate buttons with ActionScript. Button instance names are displayed in the Movie Explorer and in the Insert Target Path dialog box in the Actions panel.

The Button class inherits from the Object class.

See also

Object class


Public Properties
 Property
  _alpha : Number
The alpha transparency value of the button specified by my_btn.
  blendMode : Object
The blend mode for the button.
  cacheAsBitmap : Boolean
If set to true, Flash Player caches an internal bitmap representation of the button.
  enabled : Boolean
A Boolean value that specifies whether a button is enabled.
  filters : Array
An indexed array containing each filter object currently associated with the button.
  _focusrect : Boolean
A Boolean value that specifies whether a button has a yellow rectangle around it when it has keyboard focus.
  _height : Number
The height of the button, in pixels.
  _highquality : Number
Deprecated since Flash Player 7 — This property was deprecated in favor of Button._quality.
  menu : ContextMenu
Associates the ContextMenu object contextMenu with the button object my_button.
  _name : String
Instance name of the button specified by my_btn.
  _parent : MovieClip
A reference to the movie clip or object that contains the current movie clip or object.
  _quality : String
Property (global); sets or retrieves the rendering quality used for a SWF file.
  _rotation : Number
The rotation of the button, in degrees, from its original orientation.
  scale9Grid : Rectangle
The rectangular region that defines the nine scaling regions for the button.
  _soundbuftime : Number
The property that specifies the number of seconds a sound prebuffers before it starts to stream.
  tabEnabled : Boolean
Specifies whether my_btn is included in automatic tab ordering.
  tabIndex : Number
Lets you customize the tab ordering of objects in a SWF file.
  _target : String
[read-only]Returns the target path of the button instance specified by my_btn.
  trackAsMenu : Boolean
A Boolean value that indicates whether other buttons or movie clips can receive mouse release events.
  _url : String
[read-only]Retrieves the URL of the SWF file that created the button.
  useHandCursor : Boolean
A Boolean value that, when set to true (the default), indicates whether a pointing hand (hand cursor) displays when the mouse rolls over a button.
  _visible : Boolean
A Boolean value that indicates whether the button specified by my_btn is visible.
  _width : Number
The width of the button, in pixels.
  _x : Number
An integer that sets the x coordinate of a button relative to the local coordinates of the parent movie clip.
  _xmouse : Number
[read-only]Returns the x coordinate of the mouse position relative to the button.
  _xscale : Number
The horizontal scale of the button as applied from the registration point of the button, expressed as a percentage.
  _y : Number
The y coordinate of the button relative to the local coordinates of the parent movie clip.
  _ymouse : Number
[read-only]Indicates the y coordinate of the mouse position relative to the button.
  _yscale : Number
The vertical scale of the button as applied from the registration point of the button, expressed as a percentage.
 Properties inherited from class Object
 __proto__, __resolve, constructor, prototype
Public Methods
 Method
  
Returns the depth of the button instance.
 Methods inherited from class Object
 addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch
Events
 EventSummaryDefined by
  
onDragOut = function() {}
Invoked when the mouse button is clicked over the button and the pointer then dragged outside of the button.Button
  
onDragOver = function() {}
Invoked when the user presses and drags the mouse button outside and then over the button.Button
  
onKeyDown = function() {}
Invoked when a button has keyboard focus and a key is pressed.Button
  
onKeyUp = function() {}
Invoked when a button has input focus and a key is released.Button
  
onKillFocus = function(newFocus:Object) {}
Invoked when a button loses keyboard focus.Button
  
onPress = function() {}
Invoked when a button is pressed.Button
  
onRelease = function() {}
Invoked when a button is released.Button
  
onReleaseOutside = function() {}
Invoked when the mouse is released while the pointer is outside the button after the button is pressed while the pointer is inside the button.Button
  
onRollOut = function() {}
Invoked when the pointer moves outside a button area.Button
  
onRollOver = function() {}
Invoked when the pointer moves over a button area.Button
  
onSetFocus = function(oldFocus:Object) {}
Invoked when a button receives keyboard focus.Button
Property detail
_alphaproperty
public var _alpha:Number

Player version: Flash Player 6

The alpha transparency value of the button specified by my_btn. Valid values are 0 (fully transparent) to 100 (fully opaque). The default value is 100. Objects in a button with _alpha set to 0 are active, even though they are invisible.

See also


Example
The following code sets the _alpha property of a button named myBtn_btn to 50% when the user clicks the button. First, add a Button instance on the Stage. Second, give it an instance name of myBtn_btn. Lastly, with frame 1 selected, place the following code into the Actions panel:
myBtn_btn.onRelease = function(){
    this._alpha = 50;
};

blendModeproperty 
public var blendMode:Object

Player version: Flash Player 8

The blend mode for the button. The blend mode affects the appearance of the button when it is in a layer above another object onscreen.

Flash Player applies the blendMode property on each pixel of the button. Each pixel is composed of three constituent colors (red, green, and blue), and each constituent color has a value between 0x00 and 0xFF. Flash Player compares each constituent color of one pixel in the button with the corresponding color of the pixel in the background. For example, if blendMode is set to "lighten", Flash Player compares the red value of the button with the red value of the background, and uses the lighter of the two as the value for the red component of the displayed color.

The following table describes the blendMode settings. To set the blendMode property, you can use either an integer from 1 to 14 or a string. The illustrations in the table show blendMode applied to a button (2) when superimposed on another onscreen object (1).

Square Number 1 Circle Number 2

Integer value String value Illustration Description
1 "normal" blend mode NORMAL The button appears in front of the background. Pixel values of the button override those of the background. Where the button is transparent, the background is visible.
2 "layer" blend mode LAYER Forces the creation of a temporary buffer for precomposition for the button. This is done automatically if there is more than one child object in a button and a blendMode setting other than "normal" is selected for the child.
3 "multiply" blend mode MULTIPLY Multiplies the values of the button constituent colors by those of the background color, and then normalizes by dividing by 0xFF, resulting in darker colors. This is commonly used for shadows and depth effects.

For example, if a constituent color (such as red) of one pixel in the button and the corresponding color of the pixel in the background both have the value 0x88, the multiplied result is 0x4840. Dividing by 0xFF yields a value of 0x48 for that constituent color, which is a darker shade than that of the button or that of the background.

4 "screen" blend mode SCREEN Multiplies the complement (inverse) of the button color by the complement of the background color, resulting in a bleaching effect. This setting is commonly used for highlights or to remove black areas of the button.
5 "lighten" blend mode LIGHTEN Selects the lighter of the constituent colors of the button and those of the background (the ones with the larger values). This setting is commonly used for superimposing type.

For example, if the button has a pixel with an RGB value of 0xFFCC33, and the background pixel has an RGB value of 0xDDF800, then the resulting RGB value for the displayed pixel is 0xFFF833 (because 0xFF > 0xDD, 0xCC < 0xF8, and 0x33 > 0x00 = 33).

6 "darken" blend mode DARKEN Selects the darker of the constituent colors of the button and those of the background (the ones with the smaller values). This setting is commonly used for superimposing type.

For example, if the button has a pixel with an RGB value of 0xFFCC33, and the background pixel has an RGB value of 0xDDF800, the resulting RGB value for the displayed pixel is 0xDDCC00 (because 0xFF > 0xDD, 0xCC < 0xF8, and 0x33 > 0x00 = 33).

7 "difference" blend mode DIFFERENCE Compares the constituent colors of the button with those of its background, and subtracts the darker of the two constituent colors from the lighter one. This setting is commonly used for more vibrant colors.

For example, if the button has a pixel with an RGB value of 0xFFCC33, and the background pixel has an RGB value of 0xDDF800, the resulting RGB value for the displayed pixel is 0x222C33 (because 0xFF - 0xDD = 0x22, 0xF8 - 0xCC = 0x2C, and 0x33 - 0x00 = 0x33).

8 "add" blend mode CENTER Adds the values of the constituent colors of the button to those of its background, and applies a ceiling of 0xFF. This setting is commonly used for animating a lightening dissolve between two objects.

For example, if the button has a pixel with an RGB value of 0xAAA633, and the background pixel has an RGB value of 0xDD2200, the resulting RGB value for the displayed pixel is 0xFFC833 (because 0xAA + 0xDD > 0xFF, 0xA6 + 0x22 = 0xC8, and 0x33 + 0x00 = 0x33).

9 "subtract" blend mode SUBTRACT Subtracts the value of the constituent colors in the button from those of the background, and applies a floor of 0. This setting is commonly used for animating a darkening dissolve between two objects.

For example, if the button has a pixel with an RGB value of 0xAA2233, and the background pixel has an RGB value of 0xDDA600, the resulting RGB value for the displayed pixel is 0x338400 (because 0xDD - 0xAA = 0x33, 0xA6 - 0x22 = 0x84, and 0x00 - 0x33 < 0x00).

10 "invert" blend mode INVERT Inverts the background.
11 "alpha" blend mode ALPHA Applies the alpha value of each pixel of the button to the background. This requires the "layer" blendMode to be applied to a parent button. For example, in the illustration, the parent button, which is a white background, has blendMode = "layer".
12 "erase" blend mode CENTER Erases the background based on the alpha value of the button. This requires the "layer" blendMode setting to be applied to a parent button. For example, in the illustration, the parent button, which is a white background, has blendMode = "layer".
13 "overlay" blend mode OVERLAY Adjusts the color of each bitmap based on the darkness of the background. If the background is lighter than 50% gray, the button and background colors are screened, which results in a lighter color. If the background is darker than 50% gray, the colors are multiplied, which results in a darker color. This setting is commonly used for shading effects.
14 "hardlight" blend mode HARDLIGHT Adjusts the color of each bitmap based on the darkness of the button. If the button is lighter than 50% gray, the button and background colors are screened, which results in a lighter color. If the button is darker than 50% gray, the colors are multiplied, which results in a darker color. This setting is commonly used for shading effects.

If you attempt to set the blendMode property to any other value, Flash Player sets it to "normal".

See also


Example
In the following example you can see that if you set the property to an integer, Flash Player converts the value to the corresponding string version:
my_button.blendMode = 8;
trace (my_button.blendMode) // add

For a related example, see the description of the blendMode property of the MovieClip class.

cacheAsBitmapproperty 
public var cacheAsBitmap:Boolean

Player version: Flash Player 8

If set to true, Flash Player caches an internal bitmap representation of the button. This can increase performance for buttons that contain complex vector content.

For a button that has cacheAsBitmap set to true, Flash Player stores a bitmap representation for each of the four button states.

All vector data for a button that has a cached bitmap is drawn to the bitmap instead of the main stage. The bitmap is then copied to the main stage as unstretched, unrotated pixels snapped to the nearest pixel boundaries. Pixels are mapped one to one with the parent object. If the bounds of the bitmap change, the bitmap is recreated instead of being stretched.

No internal bitmap is created unless the cacheAsBitmap property is set to true.

After you set a button's cacheAsBitmap property to true, the rendering does not change; however, the button performs pixel snapping automatically. The animation speed can be significantly faster depending on the complexity of the vector content.

The cacheAsBitmap property is automatically set to true whenever you apply a filter to a button (when its filter array is not empty), and if a button has a filter applied to it, cacheAsBitmap is reported as true for that button, even if you set the property to false. If you clear all filters for a button, the cacheAsBitmap setting changes to what it was last set to.

In the following cases a button does not use a bitmap, even if the cacheAsBitmap property is set to true and instead renders from vector data:

The cacheAsBitmap property is best used with buttons that have mostly static content and that do not scale and rotate frequently. With such buttons, cacheAsBitmap can lead to performance increases when the button is translated (when its x and y position is changed).


Example
The following example applies a drop shadow to an existing Button instance named myButton. It then traces out the value of cacheAsBitmap, which is set to true when a filter is applied.
import flash.filters.DropShadowFilter;
trace(myButton.cacheAsBitmap); // false
var dropShadow:DropShadowFilter = new DropShadowFilter(6, 45, 0x000000, 50, 5, 5, 1, 2, false, false, false); 
myButton.filters = new Array(dropShadow);
trace(myButton.cacheAsBitmap); // true

enabledproperty 
public var enabled:Boolean

Player version: Flash Player 6

A Boolean value that specifies whether a button is enabled. When a button is disabled (the enabled property is set to false), the button is visible but cannot be clicked. The default value is true. This property is useful if you want to disable part of your navigation; for example, you may want to disable a button in the currently displayed page so that it can't be clicked and the page cannot be reloaded.


Example
The following example demonstrates how you can disable and enable buttons from being clicked. Two buttons, myBtn1_btn and myBtn2_btn, are on the Stage and the following ActionScript is added so that the myBtn2_btn button cannot be clicked. First, add two button instances on the Stage. Second, give them instance names of myBtn1_btn and myBtn2_btn. Lastly, place the following code on frame 1 to enable or disable buttons.
myBtn1_btn.enabled = true;
myBtn2_btn.enabled = false;

//button code
// the following function will not get called 
// because myBtn2_btn.enabled was set to false
myBtn1_btn.onRelease = function() {
    trace( "you clicked : " + this._name );
};
myBtn2_btn.onRelease = function() {
    trace( "you clicked : " + this._name );
};

filtersproperty 
public var filters:Array

Player version: Flash Player 8

An indexed array containing each filter object currently associated with the button. The flash.filters package contains several classes that define specific filters that you can use.

Filters can be applied in the Flash authoring tool at design-time, or at runtime using ActionScript code. To apply a filter using ActionScript, you must make a temporary copy of the entire Button.filters array, modify the temporary array, and then assign the value of the temporary array back to the Button.filters array. You cannot directly add a new filter object to the Button.filters array. The following code has no effect on the target button, named myButton:

myButton.filters[0].push(myDropShadow);

To add a filter using ActionScript, you must follow these steps (assume that the target button is named myButton):

  1. Create a new filter object using the constructor function of your chosen filter class.
  2. Assign the value of the myButton.filters array to a temporary array, such as one named myFilters.
  3. Add the new filter object to the temporary array, myFilters.
  4. Assign the value of the temporary array to the myButton.filters array.

If the filters array is empty, you need not use a temporary array. Instead, you can directly assign an array literal that contains one or more filter objects that you have created.

To modify an existing filter object, whether it was created at design-time or at runtime, you must use the technique of modifying a copy of the filters array:

To clear the filters for a button, set filters to an empty array ([]).

At load time, if a button has an associated filter, it is marked to cache itself as a transparent bitmap. From this point forward, as long as the button has a valid filter list, the player caches the button as a bitmap. This bitmap is used as a source image for the filter effects. Each button usually has two sets of bitmaps: one with the original unfiltered source button and another for the final images (in each of the four button states) after filtering. The final image set is used when rendering. As long as the button does not change, the final image does not need updating.

If you are working with a filters array that contains multiple filters and you need to track the type of filter assigned to each array index, you can maintain your own filters array and use a separate data structure to track the type of filter associated with each array index. There is no simple way to determine the type of filter associated with each filters array index.

See also


Example
The following example adds a drop shadow filter to a button named myButton.
import flash.filters.DropShadowFilter;
var myDropFilter:DropShadowFilter = new DropShadowFilter(6, 45, 0x000000, 50, 5, 5, 1, 2, false, false, false); 
var myFilters:Array = myButton.filters;
myFilters.push(myDropFilter);
myButton.filters = myFilters;

The following example changes the quality setting of the first filter in the array to 15 (this example works only if at least one filter object has been associated with the myButton text field).

var myList:Array = myButton.filters;
myList[0].quality = 15;
myButton.filters = myList;

_focusrectproperty 
public var _focusrect:Boolean

Player version: Flash Player 6

A Boolean value that specifies whether a button has a yellow rectangle around it when it has keyboard focus. This property can override the global _focusrect property. By default, the _focusrect property of a button instance is null; meaning, the button instance does not override the global _focusrect property. If the _focusrect property of a button instance is set to true or false, it overrides the setting of the global _focusrect property for the single button instance.

In Flash Player 4 or Flash Player 5 SWF files, the _focusrect property controls the global _focusrect property. It is a Boolean value. This behavior was changed in Flash Player 6 and later to permit customizing the _focusrect property on an individual movie clip.

If the _focusrect property is set to false, then keyboard navigation for that button 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.


Example
This example demonstrates how to hide the yellow rectangle around a specified button instance in a SWF file when it has focus in a browser window. Create three buttons called myBtn1_btn, myBtn2_btn, and myBtn3_btn, and add the following ActionScript to Frame 1 of the Timeline:
myBtn2_btn._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. You will not be able to execute code for this button by pressing Enter or the Space key when _focusrect is disabled.

_heightproperty 
public var _height:Number

Player version: Flash Player 6

The height of the button, in pixels.


Example
The following example sets the height and width of a button called my_btn to a specified width and height.
my_btn._width = 500;
my_btn._height = 200;

_highqualityproperty 
public var _highquality:NumberDeprecated since Flash Player 7 — This property was deprecated in favor of Button._quality.

Player version: Flash Player 6

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 smooths bitmaps if the SWF file does not contain animation and is the default value. Specify 0 (low quality) to prevent anti-aliasing.

See also


Example
Add a button instance on the Stage and name it myBtn_btn. Draw an oval on the Stage using the Oval tool that has a stroke and fill color. Select Frame 1 and add the following ActionScript using the Actions panel:
myBtn_btn.onRelease = function() {
    myBtn_btn._highquality = 0;
};
When you click myBtn_btn, the circle's stroke will look jagged. You could add the following ActionScript instead to affect the SWF globally:
_quality = 0;

menuproperty 
public var menu:ContextMenu

Player version: Flash Player 7

Associates the ContextMenu object contextMenu with the button object my_button. The ContextMenu class lets you modify the context menu that appears when the user right-clicks (Windows) or Control-clicks (Macintosh) in Flash Player.

See also


Example
The following example assigns a ContextMenu object to a button instance named myBtn_btn. The ContextMenu object contains a single menu item (labeled "Save...") with an associated callback handler function named doSave.

Add the button instance to the Stage and name it myBtn_btn.

var menu_cm:ContextMenu = new ContextMenu();
menu_cm.customItems.push(new ContextMenuItem("Save...", doSave));
function doSave(menu:Object, obj:Object):Void {
    trace( " You selected the 'Save...' menu item ");
}
myBtn_btn.menu = menu_cm;

Select Control > Test Movie to test the SWF file. With the pointer over myBtn_btn, right-click or Control-click. The context menu appears with Save in the menu. When you select Save from the menu, the Output panel appears.

_nameproperty 
public var _name:String

Player version: Flash Player 6

Instance name of the button specified by my_btn.


Example
The following example traces all instance names of any Button instances within the current Timeline of a SWF file.
for (i in this) {
    if (this[i] instanceof Button) {
    trace(this[i]._name);
    }
}

_parentproperty 
public var _parent:MovieClip

Player version: Flash Player 6

A reference to the movie clip or object that contains the current movie clip or object. The current object is the one 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. You can use _parent to move up multiple levels in the display list as in the following:

this._parent._parent._alpha = 20;

See also


Example
In the following example, a button named my_btn is placed inside a movie clip called my_mc. The following code shows how to use the _parent property to get a reference to the movie clip my_mc:
trace(my_mc.my_btn._parent);

The Output panel displays the following:

_level0.my_mc

_qualityproperty 
public var _quality:String

Player version: Flash Player 6

Property (global); sets or retrieves the rendering quality used for a SWF file. Device fonts are always aliased and therefore are unaffected by the _quality property.

The _quality property can be set to the following values:

Note: Although you can specify this property for a Button object, it is actually a global property, and you can specify its value simply as _quality.


Example
This example sets the rendering quality of a button named my_btn to LOW:
my_btn._quality = "LOW";

_rotationproperty 
public var _rotation:Number

Player version: Flash Player 6

The rotation of the button, in degrees, from its original orientation. Values from 0 to 180 represent clockwise rotation; values from 0 to -180 represent counterclockwise rotation. Values outside this range are added to or subtracted from 360 to obtain a value within the range. For example, the statement my_btn._rotation = 450 is the same as my_btn._rotation = 90.

See also


Example
The following example rotates two buttons on the Stage. Create two buttons on the Stage called control_btn and my_btn. Make sure that my_btn is not perfectly round, so you can see it rotating. Then enter the following ActionScript in Frame 1 of the Timeline:
var control_btn:Button;
var my_btn:Button;
control_btn.onRelease = function() {
    my_btn._rotation += 10;
};

Now create another button on the Stage called myOther_btn, making sure it isn't perfectly round (so you can see it rotate). Enter the following ActionScript in Frame 1 of the Timeline.

var myOther_btn:Button;
this.createEmptyMovieClip("rotater_mc", this.getNextHighestDepth());
rotater_mc.onEnterFrame = function() {
    myOther_btn._rotation += 2;
};

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components' DepthManager class instead of the MovieClip.getNextHighestDepth() method.

scale9Gridproperty 
public var scale9Grid:Rectangle

Player version: Flash Player 8

The rectangular region that defines the nine scaling regions for the button. If set to null, the entire button is scaled normally when any scale transformation is applied.

When you define a scale9Grid property for a button, the button is divided into a grid with nine regions based on the scale9Grid rectangle, which defines the center region of the grid. There are eight other regions of the grid, as follows:

You can think of the eight regions outside of the center (defined by the rectangle) as a picture frame that has special rules applied to it when the button is scaled.

When the scale9Grid property is set and a button is scaled, all text and gradients are scaled normally; however, for other types of objects the following rules apply:

If a button is rotated, all subsequent scaling is normal, and the scale9Grid property is ignored.

A common use for the scale9Grid property is to set up a button in which edge lines retain the same width when the button is scaled.

For more information, including illustrations and a related example, see MovieClip.scale9Grid.

See also

_soundbuftimeproperty 
public var _soundbuftime:Number

Player version: Flash Player 6

The property that specifies the number of seconds a sound prebuffers before it starts to stream.

Note: Although you can specify this property for a Button object, it is actually a global property that applies to all loaded sounds, and you can specify its value simply as _soundbuftime. Setting this property for a Button object actually sets the global property.

For more information and an example, see the _soundbuftime global property.

See also

tabEnabledproperty 
public var tabEnabled:Boolean

Player version: Flash Player 6

Specifies whether my_btn is included in automatic tab ordering. It is undefined by default.

If the tabEnabled property is undefined or true, the object is included in automatic tab ordering. If the tabIndex property is also set to a value, the object is included in custom tab ordering as well. If tabEnabled is false, the object is not included in automatic or custom tab ordering, even if the tabIndex property is set.

See also


Example
The following ActionScript is used to set the tabEnabled property for one of four buttons to false. However, all four buttons (one_btn, two_btn, three_btn, and four_btn) are placed in a custom tab order using tabIndex. Although tabIndex is set for three_btn, three_btn is not included in a custom or automatic tab order because tabEnabled is set to false for that instance. To set the tab ordering for the four buttons, add the following ActionScript to Frame 1 of the Timeline:
three_btn.tabEnabled = false;
two_btn.tabIndex = 1;
four_btn.tabIndex = 2;
three_btn.tabIndex = 3;
one_btn.tabIndex = 4;

Make sure that you disable keyboard shortcuts when you test the SWF file by selecting Control > Disable Keyboard Shortcuts in the test environment.

tabIndexproperty 
public var tabIndex:Number

Player version: Flash Player 6

Lets you customize the tab ordering of objects in a SWF file. You can set the tabIndex property on a button, movie clip, or text field instance; it is undefined by default.

If any currently displayed object in the SWF file contains a tabIndex property, automatic tab ordering is disabled, and the tab ordering is calculated from the tabIndex properties of objects in the SWF file. The custom tab ordering only includes objects that have tabIndex properties.

The tabIndex property may be a non-negative integer. The objects are ordered according to their tabIndex properties, in ascending order. An object with a tabIndex value of 1 precedes an object with a tabIndex value of 2. If two objects have the same tabIndex value, the one that precedes the other in the tab ordering is undefined.

The custom tab ordering defined by the tabIndex property is flat. This means that no attention is paid to the hierarchical relationships of objects in the SWF file. All objects in the SWF file with tabIndex properties are placed in the tab order, and the tab order is determined by the order of the tabIndex values. If two objects have the same tabIndex value, the one that goes first is undefined. You shouldn't use the same tabIndex value for multiple objects.

See also


Example
The following ActionScript is used to set the tabEnabled property for one of four buttons to false. However, all four buttons (one_btn, two_btn, three_btn, and four_btn) are placed in a custom tab order using tabIndex. Although tabIndex is set for three_btn, three_btn is not included in a custom or automatic tab order because tabEnabled is set to false for that instance. To set the tab ordering for the four buttons, add the following ActionScript to Frame 1 of the Timeline:
three_btn.tabEnabled = false;
two_btn.tabIndex = 1;
four_btn.tabIndex = 2;
three_btn.tabIndex = 3;
one_btn.tabIndex = 4;

Make sure that you disable keyboard shortcuts when you test the SWF file by selecting Control > Disable Keyboard Shortcuts in the test environment.

_targetproperty 
_target:String  [read-only]

Player version: Flash Player 6

Returns the target path of the button instance specified by my_btn.

Implementation
    public function get _target():String

See also


Example
Add a button instance to the Stage with an instance name my_btn and add the following code to Frame 1 of the Timeline:
trace(my_btn._target); //displays /my_btn

Select my_btn and convert it to a movie clip. Give the new movie clip an instance name my_mc. Delete the existing ActionScript in Frame 1 of the Timeline and replace it with:

my_mc.my_btn.onRelease = function(){
    trace(this._target); //displays /my_mc/my_btn
};

To convert the notation from slash notation to dot notation, modify the previous code example to the following:

my_mc.my_btn.onRelease = function(){
    trace(eval(this._target)); //displays _level0.my_mc.my_btn
};

This lets you access methods and parameters of the target object, such as:

my_mc.my_btn.onRelease = function(){
    var target_btn:Button = eval(this._target);
trace(target_btn._name); //displays my_btn
};

trackAsMenuproperty 
public var trackAsMenu:Boolean

Player version: Flash Player 6

A Boolean value that indicates whether other buttons or movie clips can receive mouse release events. If you drag a button and then release on a second button, the onRelease event is registered for the second button. This allows you to create menus. You can set the trackAsMenu property on any button or movie clip object. If the trackAsMenu property has not been defined, the default behavior is false.

You can change the trackAsMenu property at any time; the modified button immediately takes on the new behavior.

See also


Example
The following example demonstrates how to track two buttons as a menu. Place two button instances on the Stage called one_btn and two_btn. Enter the following ActionScript in the Timeline:
var one_btn:Button;
var two_btn:Button;
one_btn.trackAsMenu = true;
two_btn.trackAsMenu = true
one_btn.onRelease = function() {
    trace("clicked one_btn");
};
two_btn.onRelease = function() {
    trace("clicked two_btn");
};

Test the SWF file by clicking the Stage over one_btn, holding the mouse button down and releasing it over two_btn. Then try commenting out the two lines of ActionScript that contain trackAsMenu and test the SWF file again to see the difference in button behavior.

_urlproperty 
_url:String  [read-only]

Player version: Flash Player 6

Retrieves the URL of the SWF file that created the button.

Implementation
    public function get _url():String

Example
Create two button instances on the Stage called one_btn and two_btn. Enter the following ActionScript in Frame 1 of the Timeline:
var one_btn:Button;
var two_btn:Button;
this.createTextField("output_txt", 999, 0, 0, 100, 22);
output_txt.autoSize = true;
one_btn.onRelease = function() {
    trace("clicked one_btn");
    trace(this._url);
};
two_btn.onRelease = function() {
    trace("clicked "+this._name);
    var url_array:Array = this._url.split("/");
    var my_str:String = String(url_array.pop());
    output_txt.text = unescape(my_str);
};

When you click each button, the file name of the SWF containing the buttons displays in the Output panel.

useHandCursorproperty 
public var useHandCursor:Boolean

Player version: Flash Player 6

A Boolean value that, when set to true (the default), indicates whether a pointing hand (hand cursor) displays when the mouse rolls over a button. If this property is set to false, the arrow pointer is used instead.

You can change the useHandCursor property at any time; the modified button immediately takes on the new cursor behavior. The useHandCursor property can be read out of a prototype object.


Example
Create two buttons on the Stage with the instance names myBtn1_btn and myBtn2_btn. Enter the following ActionScript in Frame 1 of the Timeline:
myBtn1_btn.useHandCursor = false;
myBtn1_btn.onRelease = buttonClick;
myBtn2_btn.onRelease = buttonClick;
function buttonClick() {
    trace(this._name);
}

When the mouse is over and clicks myBtn1_btn, there is no pointing hand. However, you see the pointing hand when the button is over and clicks myBtn2_btn.

_visibleproperty 
public var _visible:Boolean

Player version: Flash Player 6

A Boolean value that indicates whether the button specified by my_btn is visible. Buttons that are not visible (_visible property set to false) are disabled.

See also


Example
Create two buttons on the Stage with the instance names myBtn1_btn and myBtn2_btn. Enter the following ActionScript in Frame 1 of the Timeline:
myBtn1_btn.onRelease = function() {
    this._visible = false;
    trace("clicked "+this._name);
};
myBtn2_btn.onRelease = function() {
    this._alpha = 0;
    trace("clicked "+this._name);
};

Notice how you can still click myBtn2_btn after the alpha is set to 0.

_widthproperty 
public var _width:Number

Player version: Flash Player 6

The width of the button, in pixels.

See also


Example
The following example increases the width property of a button called my_btn, and displays the width in the Output panel. Enter the following ActionScript in Frame 1 of the Timeline:
my_btn.onRelease = function() {
    trace(this._width);
    this._width *= 1.1;
};

_xproperty 
public var _x:Number

Player version: Flash Player 6

An integer that sets the x coordinate of a button relative to the local coordinates of the parent movie clip. If a button is on the main Timeline, then its coordinate system refers to the upper left corner of the Stage as (0, 0). If the button is inside a movie clip that has transformations, the button is in the local coordinate system of the enclosing movie clip. Thus, for a movie clip rotated 90 degrees counterclockwise, the enclosed button inherits a coordinate system that is rotated 90 degrees counterclockwise. The button's coordinates refer to the registration point position.

See also


Example
The following example sets the coordinates of my_btn to 0 on the Stage. Create a button called my_btn and enter the following ActionScript in Frame 1 of the Timeline:
my_btn._x = 0;
my_btn._y = 0;

_xmouseproperty 
_xmouse:Number  [read-only]

Player version: Flash Player 6

Returns the x coordinate of the mouse position relative to the button.

Implementation
    public function get _xmouse():Number

See also


Example
The following example displays the xmouse position for the Stage and a button called my_btn that is placed on the Stage. Enter the following ActionScript in Frame 1 of the Timeline:
this.createTextField("mouse_txt", 999, 5, 5, 150, 40);
mouse_txt.html = true;
mouse_txt.wordWrap = true;
mouse_txt.border = true;
mouse_txt.autoSize = true;
mouse_txt.selectable = false;
//
var mouseListener:Object = new Object();
mouseListener.onMouseMove = function() {
    var table_str:String = "<textformat tabstops='[50,100]'>";
    table_str += "<b>Stage</b>\t"+"x:"+_xmouse+"\t"+"y:"+_ymouse+newline;
    table_str += "<b>Button</b>\t"+"x:"+my_btn._xmouse+"\t"+"y:"+my_btn._ymouse+newline;
    table_str += "</textformat>";
    mouse_txt.htmlText = table_str;
};
Mouse.addListener(mouseListener);

_xscaleproperty 
public var _xscale:Number

Player version: Flash Player 6

The horizontal scale of the button as applied from the registration point of the button, expressed as a percentage. The default registration point is (0,0).

Scaling the local coordinate system affects the _x and _y property settings, which are defined in pixels. For example, if the parent movie clip is scaled to 50%, setting the _x property moves an object in the button by half the number of pixels that it would if the SWF file were at 100%.

See also


Example
The following example scales a button called my_btn. When you click and release the button, it grows 10% on the x and y axis. Enter the following ActionScript in Frame 1 of the Timeline:
my_btn.onRelease = function(){
    this._xscale *= 1.1;
    this._yscale *= 1.1;
};

_yproperty 
public var _y:Number

Player version: Flash Player 6

The y coordinate of the button relative to the local coordinates of the parent movie clip. If a button is in the main Timeline, its coordinate system refers to the upper left corner of the Stage as (0, 0). If the button is inside another movie clip that has transformations, the button is in the local coordinate system of the enclosing movie clip. Thus, for a movie clip rotated 90 degrees counterclockwise, the enclosed button inherits a coordinate system that is rotated 90 degrees counterclockwise. The button's coordinates refer to the registration point position.

See also


Example
The following example sets the coordinates of my_btn to 0 on the Stage. Create a button called my_btn and enter the following ActionScript in Frame 1 of the Timeline:
my_btn._x = 0;
my_btn._y = 0;

_ymouseproperty 
_ymouse:Number  [read-only]

Player version: Flash Player 6

Indicates the y coordinate of the mouse position relative to the button.

Implementation
    public function get _ymouse():Number

See also


Example
The following example displays the ymouse position for the Stage and a button called my_btn that is placed on the Stage. Enter the following ActionScript in Frame 1 of the Timeline:
this.createTextField("mouse_txt", 999, 5, 5, 150, 40);
mouse_txt.html = true;
mouse_txt.wordWrap = true;
mouse_txt.border = true;
mouse_txt.autoSize = true;
mouse_txt.selectable = false;
//
var mouseListener:Object = new Object();
mouseListener.onMouseMove = function() {
    var table_str:String = "<textformat tabstops='[50,100]'>";
    table_str += "<b>Stage</b>\t"+"x:"+_xmouse+"\t"+"y:"+_ymouse+newline;
    table_str += "<b>Button</b>\t"+"x:"+my_btn._xmouse+"\t"+"y:"+my_btn._ymouse+newline;
    table_str += "</textformat>";
    mouse_txt.htmlText = table_str;
};
Mouse.addListener(mouseListener);

_yscaleproperty 
public var _yscale:Number

Player version: Flash Player 6

The vertical scale of the button as applied from the registration point of the button, expressed as a percentage. The default registration point is (0,0).

See also


Example
The following example scales a button called my_btn. When you click and release the button, it grows 10% on the x and y axis. Enter the following ActionScript in Frame 1 of the Timeline:
my_btn.onRelease = function(){
    this._xscale *= 1.1;
    this._yscale *= 1.1;
};

Method detail
getDepth()method
public function getDepth():Number

Player version: Flash Player 6

Returns the depth of the button instance.

Each movie clip, button, and text field has a unique depth associated with it that determines how the object appears in front of or in back of other objects. Objects with higher depths appear in front.

Returns
Number — The depth of the button instance.

See also


Example
If you create myBtn1_btn and myBtn2_btn on the Stage, you can trace their depth using the following ActionScript:
trace(myBtn1_btn.getDepth());
trace(myBtn2_btn.getDepth());

If you load a SWF file called buttonMovie.swf into this document, you could trace the depth of a button, myBtn4_btn, inside that SWF file using another button in the main SWF file:

this.createEmptyMovieClip("myClip_mc", 999);
myClip_mc.loadMovie("buttonMovie.swf");
myBtn3_btn.onRelease = function(){
    trace(myClip_mc.myBtn4_btn.getDepth());
};

You might notice that two of these buttons, one in the main SWF file and one in the loaded SWF file, have the same depth value. This is misleading because buttonMovie.swf was loaded at depth 999, which means that the button it contains will also have a depth of 999 relative to the buttons in the main SWF file. You should keep in mind that each movie clip has its own internal z-order, which means that each movie clip has its own set of depth values. The two buttons may have the same depth value, but the values only have meaning in relation to other objects in the same z-order. In this case, the buttons have the same depth value, but the values relate to different movie clips. For example, the depth value of the button in the main SWF file relates to the z-order of the main timeline, while the depth value of the button in the loaded SWF file relates to the internal z-order of the myClip_mc movie clip.

Event detail
onDragOutevent handler

public onDragOut = function() {}

Player version: Flash Player 6

Invoked when the mouse button is clicked over the button and the pointer then dragged outside of the button. You must define a function that executes when the event handler is invoked.


Example
The following example demonstrates how you can execute statements when the pointer is dragged off a button. Create a button called my_btn on the Stage and enter the following ActionScript in a frame on the Timeline:
my_btn.onDragOut = function() {
    trace("onDragOut: "+this._name);
};
my_btn.onDragOver = function() {
    trace("onDragOver: "+this._name);
};

onDragOverevent handler 

public onDragOver = function() {}

Player version: Flash Player 6

Invoked when the user presses and drags the mouse button outside and then over the button. You must define a function that executes when the event handler is invoked.


Example
The following example defines a function for the onDragOver handler that sends a trace() statement to the Output panel. Create a button called my_btn on the Stage and enter the following ActionScript on the Timeline:
my_btn.onDragOut = function() {
    trace("onDragOut: "+this._name);
};
my_btn.onDragOver = function() {
    trace("onDragOver: "+this._name);
};

When you test the SWF file, drag the pointer off the button instance. Then, while holding the mouse button, drag onto the button instance again. Notice that the Output panel tracks your movements.

See also

onKeyDownevent handler 

public onKeyDown = function() {}

Player version: Flash Player 6

Invoked when a button has keyboard focus and a key is pressed. The onKeyDown event handler is invoked with no parameters. You can use the Key.getAscii() and Key.getCode() methods to determine which key was pressed. You must define a function that executes when the event handler is invoked.


Example
In the following example, a function that sends text to the Output panel is defined for the onKeyDown handler. Create a button called my_btn on the Stage, and enter the following ActionScript in a frame on the Timeline:
my_btn.onKeyDown = function() {
    trace("onKeyDown: "+this._name+" (Key: "+getKeyPressed()+")");
};
function getKeyPressed():String {
    var theKey:String;
    switch (Key.getAscii()) {
    case Key.BACKSPACE :
        theKey = "BACKSPACE";
        break;
    case Key.SPACE :
        theKey = "SPACE";
        break;
    default :
        theKey = chr(Key.getAscii());
    }
    return theKey;
}

Select Control > Test Movie to test the SWF file. Make sure you select Control > Disable Keyboard Shortcuts in the test environment. Then press the Tab key until the button has focus (a yellow rectangle appears around the my_btn instance) and start pressing keys on your keyboard. When you press keys, they are displayed in the Output panel.

See also

onKeyUpevent handler 

public onKeyUp = function() {}

Player version: Flash Player 6

Invoked when a button has input focus and a key is released. The onKeyUp event handler is invoked with no parameters. You can use the Key.getAscii() and Key.getCode() methods to determine which key was pressed.


Example
In the following example, a function that sends text to the Output panel is defined for the onKeyDown handler. Create a button called my_btn on the Stage, and enter the following ActionScript in a frame on the Timeline:
my_btn.onKeyDown = function() {
    trace("onKeyDown: "+this._name+" (Key: "+getKeyPressed()+")");
};
my_btn.onKeyUp = function() {
    trace("onKeyUp: "+this._name+" (Key: "+getKeyPressed()+")");
};
function getKeyPressed():String {
    var theKey:String;
    switch (Key.getAscii()) {
    case Key.BACKSPACE :
        theKey = "BACKSPACE";
        break;
    case Key.SPACE :
        theKey = "SPACE";
        break;
    default :
        theKey = chr(Key.getAscii());
    }
    return theKey;
}

Press Control+Enter to test the SWF file. Make sure you select Control > Disable Keyboard Shortcuts in the test environment. Then press the Tab key until the button has focus (a yellow rectangle appears around the my_btn instance) and start pressing keys on your keyboard. When you press keys, they are displayed in the Output panel.

See also

onKillFocusevent handler 

public onKillFocus = function(newFocus:Object) {}

Player version: Flash Player 6

Invoked when a button loses keyboard focus. The onKillFocus handler receives one parameter, newFocus, which is an object representing the new object receiving the focus. If no object receives the focus, newFocus contains the value null.

Parameters
newFocus:Object — The object that is receiving the focus.

Example
The following example demonstrates how statements can be executed when a button loses focus. Create a button instance on the Stage called my_btn and add the following ActionScript to Frame 1 of the Timeline:
this.createTextField("output_txt", this.getNextHighestDepth(), 0, 0, 300, 200);
output_txt.wordWrap = true;
output_txt.multiline = true;
output_txt.border = true;
my_btn.onKillFocus = function() {
    output_txt.text = "onKillFocus: "+this._name+newline+output_txt.text;
};

Test the SWF file in a browser window, and try using the Tab key to move through the elements in the window. When the button instance loses focus, text is sent to the output_txt text field.

The MovieClip.getNextHighestDepth() method used in this example requires Flash Player 7 or later. If your SWF file includes a version 2 component, use the version 2 components' DepthManager class instead of the MovieClip.getNextHighestDepth() method.

onPressevent handler 

public onPress = function() {}

Player version: Flash Player 6

Invoked when a button is pressed. You must define a function that executes when the event handler is invoked.


Example
In the following example, a function that sends a trace() statement to the Output panel is defined for the onPress handler:
my_btn.onPress = function () {
    trace ("onPress called");
};

onReleaseevent handler 

public onRelease = function() {}

Player version: Flash Player 6

Invoked when a button is released. You must define a function that executes when the event handler is invoked.


Example
In the following example, a function that sends a trace() statement to the Output panel is defined for the onRelease handler:
my_btn.onRelease = function () {
    trace ("onRelease called");
};

onReleaseOutsideevent handler 

public onReleaseOutside = function() {}

Player version: Flash Player 6

Invoked when the mouse is released while the pointer is outside the button after the button is pressed while the pointer is inside the button. You must define a function that executes when the event handler is invoked.


Example
In the following example, a function that sends a trace() statement to the Output panel is defined for the onReleaseOutside handler:
my_btn.onReleaseOutside = function () {
    trace ("onReleaseOutside called");
};

onRollOutevent handler 

public onRollOut = function() {}

Player version: Flash Player 6

Invoked when the pointer moves outside a button area. You must define a function that executes when the event handler is invoked.


Example
In the following example, a function that sends a trace() statement to the Output panel is defined for the onRollOut handler:
my_btn.onRollOut = function () {
    trace ("onRollOut called");
};

onRollOverevent handler 

public onRollOver = function() {}

Player version: Flash Player 6

Invoked when the pointer moves over a button area. You must define a function that executes when the event handler is invoked.


Example
In the following example, a function that sends a trace() statement to the Output panel is defined for the onRollOver handler:
my_btn.onRollOver = function () {
    trace ("onRollOver called");
};

onSetFocusevent handler 

public onSetFocus = function(oldFocus:Object) {}

Player version: Flash Player 6

Invoked when a button receives keyboard focus. The oldFocus parameter is the object that loses the focus. For example, if the user presses the Tab key to move the input focus from a text field to a button, oldFocus contains the text field instance.

If there is no previously focused object, oldFocus contains a null value.

Parameters
oldFocus:Object — The object to lose keyboard focus.

Example
The following example demonstrates how you can execute statements when the user of a SWF file moves focus from one button to another. Create two buttons, btn1_btn and btn2_btn, and enter the following ActionScript in Frame 1 of the Timeline:
Selection.setFocus(btn1_btn);
trace(Selection.getFocus());
btn2_btn.onSetFocus = function(oldFocus) {
    trace(oldFocus._name + "lost focus");
};

Test the SWF file by pressing Control+Enter. Make sure you select Control > Disable Keyboard Shortcuts if it is not already selected. Focus is set on btn1_btn. When btn1_btn loses focus and btn2_btn gains focus, information is displayed in the Output panel.