Button Events (ActionScript: The Definitive Guide)

10.8. Button Events

Table 10-1 briefly introduces the various events available for buttons. Using button events, we can easily create code for navigation, forms, games, and other interface elements. Let's explore each button event and learn how a button can be programmed to react to mouse and keyboard events.

Each of the button events in Table 10-1 is handled by a matching button event handler of the form on (eventName). For example, the press event is handled using an event handler beginning with on (press). The exception is the keyPress event handler which takes the form on (keyPress key) where key is the key to detect. 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 descriptions, the hit area refers to the physical region of the button that must be under the mouse pointer in order for the button to be activated. (A button's hit area is defined graphically when you create the button in the Flash authoring tool.)

Table 10-1. Button Events

Button Event Name	Button Event Occurs When . . .
`press`	Primary mouse button is depressed while pointer is in the button's hit area. Other mouse buttons are not detectable.
`release`	Primary mouse button is depressed and then released while pointer is in the button's hit area.
`releaseOutside`	Primary mouse button is depressed while pointer is in the button's hit area and then released while pointer is outside of the hit area.
`rollOver`	Mouse pointer moves into the button's hit area without the mouse button depressed.
`rollOut`	Mouse pointer moves out of the button's hit area without the mouse button depressed.
`dragOut`	Primary mouse button is depressed while pointer is in the button's hit area, and then, while mouse button is still depressed, pointer is moved out of the hit area.
`dragOver`	Primary mouse button is depressed while pointer is in the button's hit area, and then, while mouse button is still depressed, pointer is moved out of, then back into, the button's hit area.
`keyPress`	Specified key is depressed. In most cases, the keyDown clip event is preferred over the keyPress button event.

10.8.1. press

A mouseclick is technically a two-step process: the mouse button is depressed ( press) and then released (release). A press event occurs when the mouse pointer is in the hit area of a button and the primary mouse button is depressed. Secondary mouse buttons are not detectable. Button press events are appropriate for radio buttons or weapons firing in a game, but use release events to allow the user to change his mind before releasing the mouse.

10.8.2. release

The release button event occurs when the following sequence is detected:

The mouse pointer is in the hit area of a button.
The primary mouse button is pressed while the mouse pointer is still in the hit area of the button (at which point a press event occurs).
The primary mouse button is released while the mouse pointer is still in the hit area of the original button (at which point the release event occurs).

By using the release event instead of the press event, you give users a chance to move the pointer off of a button even after it has been clicked, thus allowing them to retract their action.

10.8.3. releaseOutside

The releaseOutside event typically indicates that the user changed his mind by clicking on a button but moving the pointer off the button before releasing the mouse button. The event is generated when the following sequence is detected:

The mouse pointer is in the hit area of a button.
The primary mouse button is pressed and held (the press event occurs).
The mouse pointer moves out of the button's hit area (the dragOut event occurs).
The primary mouse button is released while not in the hit area of the original button.

You will rarely bother detecting releaseOutside events, as they usually indicate that the user intended not to perform any action.

The mouse pointer moves into the hit area of a button (rollOver event occurs).
The primary mouse button is pressed and held ( press event occurs).
The mouse pointer moves out of the button's hit area (dragOut event occurs).
The mouse pointer moves back into the button's hit area (dragOver event occurs).

Thus, the dragOver event indicates that the user has moved the mouse pointer out of and back into the hit area, all the while holding the mouse button down. Note that dragover, instead of the rollOver event, is generated if the mouse button is still down when the pointer reenters the button's hit area.

10.8.8. keyPress

The keyPress event is unrelated to mouse events and is instead triggered by the pressing of a specified key. We cover it here because it uses the on (eventName) syntax of other ActionScript button event handlers. This event handler requires us to specify the key that triggers the event:

on (keyPress key) {
  statements
}

where key is a string representing the key associated with the event. The string may be either the character on the key (such as "s" or "S"), or a keyword representing the key in the format "<Keyword >". Only one key may be specified with each handler. To capture multiple keys using keyPress, we must create multiple keyPress event handlers. For example:

// Detects the "a" key
on (keyPress "a") {
  trace("The 'a' key was pressed");
}

// Detects the Enter key
on (keyPress "<Enter>") {
  trace("The Enter key was pressed");
}

// Detects the Down Arrow key
on (keyPress "<Down>") {
  trace("The Down Arrow key was pressed");
}

The legal values of Keyword are as follows (note that the function keys F1 . . . F12 are not supported by keyPress, but are detectable using the Key object):

<Backspace>
<Delete>
<Down>
<End>
<Enter>
<Home>
<Insert>
<Left>
<PgDn>
<PgUp>
<Right>
<Space>
<Tab>
<Up>

In Flash 4, keyPress was the only means we had of interacting with the keyboard. In Flash 5 and later, the Key object, in combination with the movie clip events keyDown and keyUp (discussed later), offer much greater control over keyboard interaction. The keyPress event detects the pressing of a single key at a time, whereas the Key object can detect the simultaneous pressing of multiple keys.

10.8. Button Events

Table 10-1. Button Events

10.8.1. press

10.8.2. release

10.8.3. releaseOutside

10.8.4. rollOver

10.8.5. rollOut

10.8.6. dragOut

10.8.7. dragOver

10.8.8. keyPress