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
Properties inherited from class Object
Event summary
Method summary
Methods inherited from class Object
_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).
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:
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):
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. 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:
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:
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. 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) |