Button Class

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock

	Chapter 18. ActionScript Language Reference

Button Class

Flash 6

control over buttons in a movie.

Constructor

None. Button objects must be created manually in the authoring tool. Use movie clips to simulate runtime-generated buttons.

Properties

_alpha: Opacity percentage: 0 is transparent; 100 is opaque.
enabled: Boolean; allows or disallows button interaction.
_focusrect: Boolean; enables or disables automatic highlighting of buttons activated via the keyboard.
_height: Height of the button, in pixels.
_name: The instance name of the Button object.
_parent: A reference to the movie clip in which the button resides.
_rotation: Clockwise rotation, in degrees, of the button.
tabEnabled: Boolean; includes or excludes the button from the current tab order.
tabIndex: Specifies the button's index in the custom tab order.
_target: The target path of the button, in slash syntax.
trackAsMenu: Modifies the button's onRelease( ) handler requirements, enabling menu-style behavior.
_url: The network address of the movie clip that contains the button.
useHandCursor: Boolean; dictates whether a hand icon is displayed when the mouse is over the button.
_visible: Boolean; controls whether the button is shown or hidden.
_width: Width of the button, in pixels.
_x: Horizontal location of the button's registration point, in pixels.
_xmouse: Horizontal location of mouse pointer, relative to the button's registration point, in pixels.
_xscale: Width of the button, as a percentage of its original width.
_y: Vertical location of the button's registration point, in pixels.
_ymouse: Vertical location of mouse pointer, relative to the button's registration point, in pixels.
_yscale: Height of the button, as a percentage of its original height.

Methods

getDepth( ): Returns the position of the button in the content stack.

Event Handlers

on (keyPress): Occurs when the specified key is pressed.
onDragOut( ): Occurs when the mouse is clicked while the pointer is over a button and then the pointer moves off the Flash button without the mouse button being released.
onDragOver( ): Occurs when the mouse is clicked while the pointer is over a button and then the pointer moves off and back onto the Flash button without the mouse button being released.
onKillFocus( ): Occurs when the button loses focus.
onPress( ): Occurs when the mouse is clicked while the pointer is over a Flash button.
onRelease( ): Occurs when the mouse is pressed and then released while the pointer is over a Flash button.
onReleaseOutside( ): Occurs when the mouse is clicked over the Flash button and then released after rolling off the button.
onRollOut( ): Occurs when the pointer moves off the Flash button (while the mouse is not depressed).
onRollOver( ): Occurs when the pointer moves over the Flash button (while the mouse is not depressed).
onSetFocus( ): Occurs when the Flash button gains focus.

Description

The Button class provides programmatic control over the buttons in a movie. Each Button object represents a single Button symbol instance created manually at authoring time. Buttons cannot be created or destroyed via ActionScript, even though the Button class constructor technically exists for the sake of containing the class's methods and properties. That is, calling new Button( ) does not create a visual button instance for use in a movie. However, movie clips which have all the capabilities of buttons can be both created and destroyed via ActionScript at runtime. To remove a button instance, place it in movie clip, and remove the clip using MovieClip.removeMovieClip( ).

Prior to Flash 6, buttons were not accessible to ActionScript. As of Flash 6, the Button class lets us manipulate buttons much as we do movie clips, by setting position, size, rotation, etc. In fact, many button properties are borrowed directly from the MovieClip class (for example, _x, _y, _width, _height, and _rotation). For the sake of backward compatibility, button properties corresponding to movie clip properties that existed prior to Flash 6 are prefixed with an underscore (_). To conform more closely with other ECMA-262 languages, properties that are completely new in Flash 6 do not use the underscore convention.

The Button class's event handlers provide tools for creating navigation, forms, games, and other interface elements. Each type of event is described in detail later in this entry. To respond to events, a button object can use either of two different types of event handlers an event handler property:

go_btn.onPress = function () {   // statements };

or the idiosyncratic Flash 5 notation attached directly to the button in the authoring tool:

on (press) {   // statements }

However, one of the button events, keyPress, supports the Flash 5 on(keyPress) form only. See Button keyPress for details.

For general information on creating event handlers, see Chapter 10. Note that as of Flash 6, all button event handlers are also supported by the MovieClip class.

Button events are sent only to the button with which the mouse is interacting. If multiple buttons overlap, the topmost button receives all events; no other buttons can respond, even if the topmost button has no handlers defined.

In the following entries for Button property, method, and event descriptions:

The hit area refers to the physical region of the button that must be under the mouse pointer in order for the Flash button to be activated. (A Flash button's hit area is defined graphically when you create the button in the Flash authoring tool.)
The Up, Over, and Down states correspond to the button frames of the same name in the Flash authoring tool. These are displayed automatically when the mouse is not over the Flash button's hit area (Up), the mouse is over the Flash button's hit area (Over), or the mouse is depressed over the Flash button's hit area (Down).

To enable Actions panel code-hinting for button objects, use an instance name that includes the suffix "_btn", as in: submit_btn.

Usage

Using Button objects, even novice developers can add interactivity with minimal effort. However, for advanced applications, movie clips are often more appropriate than buttons. Movie clips offer all the capabilities of buttons, but with added features such as a dynamic hit area, changeable button states (Up, Over, and Down), and the full suite of MovieClip methods, events, and properties.