Button


Object   |   +-Button public class Button extends Object

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.

Availability: ActionScript 1.0; Flash Player 6

See also

Object

Property summary

Modifiers

Property

Description

 

_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. Specifies the level of anti-aliasing applied to the current SWF file.

 

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

constructor (Object.constructor property), __proto__ (Object.__proto__ property), prototype (Object.prototype property), __resolve (Object.__resolve property)


Event summary

Event

Description

onDragOut = function() {}

Invoked when the mouse button is clicked over the button and the pointer then dragged outside of the button.

onDragOver = function() {}

Invoked when the user presses and drags the mouse button outside and then over the button.

onKeyDown = function() {}

Invoked when a button has keyboard focus and a key is pressed.

onKeyUp = function() {}

Invoked when a button has input focus and a key is released.

onKillFocus = function(newFocus:Object) {}

Invoked when a button loses keyboard focus.

onPress = function() {}

Invoked when a button is pressed.

onRelease = function() {}

Invoked when a button is released.

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.

onRollOut = function() {}

Invoked when the pointer moves outside a button area.

onRollOver = function() {}

Invoked when the pointer moves over a button area.

onSetFocus = function(oldFocus:Object) {}

Invoked when a button receives keyboard focus.


Method summary

Modifiers

Signature

Description

 

geTDepth() : Number

Returns the depth of the button instance.


Methods inherited from class Object

addProperty (Object.addProperty method), hasOwnProperty (Object.hasOwnProperty method), isPropertyEnumerable (Object.isPropertyEnumerable method), isPrototypeOf (Object.isPrototypeOf method), registerClass (Object.registerClass method), toString (Object.toString method), unwatch (Object.unwatch method), valueOf (Object.valueOf method), watch (Object.watch method)


_alpha (Button._alpha property)

public _alpha : Number

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.

Availability: ActionScript 1.0; Flash Player 6

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; };

See also

_alpha (MovieClip._alpha property), _alpha (TextField._alpha property)

blendMode (Button.blendMode property)

public blendMode : Object

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).

Integer value

String value

Illustration

Description

1

"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"

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"

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"

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"

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"

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"

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"

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"

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"

Inverts the background.

11

"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"

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"

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"

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".

Availability: ActionScript 1.0; Flash Player 8

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.

See also

blendMode (MovieClip.blendMode property)

cacheAsBitmap (Button.cacheAsBitmap property)

public cacheAsBitmap : Boolean

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:

  • When the bitmap is too large, that is, greater than 2880 pixels in either direction

  • When the bitmap fails to allocate memory (due to an out of memory error)

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).

Availability: ActionScript 1.0; Flash Player 8

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

enabled (Button.enabled property)

public enabled : Boolean

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.

Availability: ActionScript 1.0; Flash Player 6

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 ); };

filters (Button.filters property)

public filters : Array

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):

  • Create a new filter object using the constructor function of your chosen filter class.

  • Assign the value of the myButton.filters array to a temporary array, such as one named myFilters.

  • Add the new filter object to the temporary array, myFilters.

  • 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:

  • Assign the value of the myButton.filters array to a temporary array, such as one named myFilters.

  • Modify the property using the temporary array, myFilters. For example, if you want to set the quality property of the first filter in the array, you could use the following code: myList[0].quality = 1;

  • Assign the value of the temporary array to the myButton.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.

Availability: ActionScript 1.0; Flash Player 8

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;

See also

, cacheAsBitmap (Button.cacheAsBitmap property)

_focusrect (Button._focusrect property)

public _focusrect : Boolean

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.

Availability: ActionScript 1.0; Flash Player 6

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.

getDepth (Button.getDepth method)

public getDepth() : Number

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.

Availability: ActionScript 1.0; Flash Player 6

Returns

Number - The depth of the button instance.

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.

See also

getDepth (MovieClip.getDepth method), getDepth (TextField.getDepth method),

_height (Button._height property)

public _height : Number

The height of the button, in pixels.

Availability: ActionScript 1.0; Flash Player 6

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;

_highquality (Button._highquality property)

public _highquality : Number

Deprecated since Flash Player 7. This property was deprecated in favor of Button._quality.

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.

Availability: ActionScript 1.0; Flash Player 6

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;

See also

_quality (Button._quality property), _quality property

menu (Button.menu property)

public menu : ContextMenu

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.

Availability: ActionScript 1.0; Flash Player 7

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.

See also

ContextMenu, ContextMenuItem, menu (MovieClip.menu property), menu (TextField.menu property)

_name (Button._name property)

public _name : String

Instance name of the button specified by my_btn.

Availability: ActionScript 1.0; Flash Player 6

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);   } }

onDragOut (Button.onDragOut handler)

onDragOut = function() {}

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.

Availability: ActionScript 1.0; Flash Player 6

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); };

onDragOver (Button.onDragOver handler)

onDragOver = function() {}

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.

Availability: ActionScript 1.0; Flash Player 6

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

onDragOut (Button.onDragOut handler)

onKeyDown (Button.onKeyDown handler)

onKeyDown = function() {}

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.

Availability: ActionScript 1.0; Flash Player 6

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

onKeyUp (Button.onKeyUp handler), getAscii (Key.getAscii method), getCode (Key.getCode method)

onKeyUp (Button.onKeyUp handler)

onKeyUp = function() {}

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.

Availability: ActionScript 1.0; Flash Player 6

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

onKeyDown (Button.onKeyDown handler), getAscii (Key.getAscii method), getCode (Key.getCode method)

onKillFocus (Button.onKillFocus handler)

onKillFocus = function(newFocus:Object) {}

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.

Availability: ActionScript 1.0; Flash Player 6

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.

onPress (Button.onPress handler)

onPress = function() {}

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

Availability: ActionScript 1.0; Flash Player 6

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"); };

onRelease (Button.onRelease handler)

onRelease = function() {}

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

Availability: ActionScript 1.0; Flash Player 6

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"); };

onReleaseOutside (Button.onReleaseOutside handler)

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. You must define a function that executes when the event handler is invoked.

Availability: ActionScript 1.0; Flash Player 6

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"); };

onRollOut (Button.onRollOut handler)

onRollOut = function() {}

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

Availability: ActionScript 1.0; Flash Player 6

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"); };

onRollOver (Button.onRollOver handler)

onRollOver = function() {}

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

Availability: ActionScript 1.0; Flash Player 6

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"); };

onSetFocus (Button.onSetFocus handler)

onSetFocus = function(oldFocus:Object) {}

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.

Availability: ActionScript 1.0; Flash Player 6

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.

_parent (Button._parent property)

public _parent : MovieClip

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;

Availability: ActionScript 1.0; Flash Player 6

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

See also

_parent (MovieClip._parent property), _target (MovieClip._target property), _root property

_quality (Button._quality property)

public _quality : String

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:

  • "LOW" Low rendering quality. Graphics are not anti-aliased, and bitmaps are not smoothed.

  • "MEDIUM" Medium rendering quality. Graphics are anti-aliased using a 2 x 2 pixel grid, but bitmaps are not smoothed. This is suitable for movies that do not contain text.

  • "HIGH" High rendering quality. Graphics are anti-aliased using a 4 x 4 pixel grid, and bitmaps are smoothed if the movie is static. This is the default rendering quality setting used by Flash.

  • "BEST" Very high rendering quality. Graphics are anti-aliased using a 4 x 4 pixel grid and bitmaps are always smoothed.

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.


Availability: ActionScript 1.0; Flash Player 6

Example

This example sets the rendering quality of a button named my_btn to LOW:

my_btn._quality = "LOW";

_rotation (Button._rotation property)

public _rotation : Number

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.

Availability: ActionScript 1.0; Flash Player 6

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.

See also

_rotation (MovieClip._rotation property), _rotation (TextField._rotation property)

scale9Grid (Button.scale9Grid property)

public scale9Grid : Rectangle

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:

  • The area in the upper-left corner outside of the rectangle

  • The area above the rectangle

  • The area in the upper-right corner outside the rectangle

  • The area to the left of the rectangle

  • The area to the right of the rectangle

  • The area in the lower-left corner outside the rectangle

  • The area below the rectangle

  • The area in the lower-right corner outside the rectangle

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:

  • Content in the center region is scaled normally.

  • Content in the corners is not scaled.

  • Content in the top and bottom regions is scaled only horizontally. Content in the left and right regions is scaled only vertically.

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.

Availability: ActionScript 1.0; Flash Player 8

See also

Rectangle (flash.geom.Rectangle), scale9Grid (MovieClip.scale9Grid property)

_soundbuftime (Button._soundbuftime property)

public _soundbuftime : Number

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 actually sets global property.


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

Availability: ActionScript 1.0; Flash Player 6

See also

_soundbuftime property

tabEnabled (Button.tabEnabled property)

public tabEnabled : Boolean

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.

Availability: ActionScript 1.0; Flash Player 6

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.

See also

tabIndex (Button.tabIndex property), tabEnabled (MovieClip.tabEnabled property), tabEnabled (TextField.tabEnabled property)

tabIndex (Button.tabIndex property)

public tabIndex : Number

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.

Availability: ActionScript 1.0; Flash Player 6

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.

See also

tabEnabled (Button.tabEnabled property), tabChildren (MovieClip.tabChildren property), tabEnabled (MovieClip.tabEnabled property), tabIndex (MovieClip.tabIndex property), tabIndex (TextField.tabIndex property)

_target (Button._target property)

public _target : String [read-only]

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

Availability: ActionScript 1.0; Flash Player 6

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 };

See also

_target (MovieClip._target property)

trackAsMenu (Button.trackAsMenu property)

public trackAsMenu : Boolean

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.

Availability: ActionScript 1.0; Flash Player 6

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.

See also

trackAsMenu (MovieClip.trackAsMenu property)

_url (Button._url property)

public _url : String [read-only]

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

Availability: ActionScript 1.0; Flash Player 6

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.

useHandCursor (Button.useHandCursor property)

public 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. 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.

Availability: ActionScript 1.0; Flash Player 6

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.

_visible (Button._visible property)

public _visible : Boolean

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.

Availability: ActionScript 1.0; Flash Player 6

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.

See also

_visible (MovieClip._visible property), _visible (TextField._visible property)

_width (Button._width property)

public _width : Number

The width of the button, in pixels.

Availability: ActionScript 1.0; Flash Player 6

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; };

See also

_width (MovieClip._width property)

_x (Button._x property)

public _x : Number

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.

Availability: ActionScript 1.0; Flash Player 6

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;

See also

_xscale (Button._xscale property), _y (Button._y property), _yscale (Button._yscale property)

_xmouse (Button._xmouse property)

public _xmouse : Number [read-only]

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

Availability: ActionScript 1.0; Flash Player 6

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);

See also

_ymouse (Button._ymouse property)

_xscale (Button._xscale property)

public _xscale : Number

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%.

Availability: ActionScript 1.0; Flash Player 6

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; };

See also

_x (Button._x property), _y (Button._y property), _yscale (Button._yscale property)

_y (Button._y property)

public _y : Number

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.

Availability: ActionScript 1.0; Flash Player 6

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;

See also

_x (Button._x property), _xscale (Button._xscale property), _yscale (Button._yscale property)

_ymouse (Button._ymouse property)

public _ymouse : Number [read-only]

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

Availability: ActionScript 1.0; Flash Player 6

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);

See also

_xmouse (Button._xmouse property)

_yscale (Button._yscale property)

public _yscale : Number

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).

Availability: ActionScript 1.0; Flash Player 6

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; };

See also

_y (Button._y property), _x (Button._x property), _xscale (Button._xscale property)



ActionScript 2.0 Language Reference for Macromedia Flash 8
ActionScript 2.0 Language Reference for Macromedia Flash 8
ISBN: 0321384040
EAN: 2147483647
Year: 2004
Pages: 113

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net